Sample: SWAPI API Documentation

Part 1 · Overview

Product Details

The Star Wars API (SWAPI) is the world's first quantified and programmatically accessible data source for the Star Wars canon universe. It provides a vast repository of planets, spaceships, vehicles, people, species, and films from the saga.

Solving Developer Problems

Structured JSON: data returned in a clean, predictable format.
Resource Linking: hypermedia links let developers traverse the universe.
Open Access: no barriers to entry for rapid prototyping.

Workflow & Getting Started

Identify the Resource — choose which data object you need (e.g., People).
Select the Endpoint — a list of all resources or a specific item by ID.
Execute GET Request — send an HTTP GET request to the Resource URL.
Process JSON — parse the JSON response for your application.

Prerequisites

An active internet connection.
A tool or library that can make HTTP requests (Postman, cURL, Python requests).

Authorization & Authentication

Type: None. SWAPI is entirely public — you do not need an API key or Bearer token to access the data.

Return Status Codes

Status Code	Description
200 OK	The request was successful.
404 Not Found	The requested resource (ID) does not exist.
429 Too Many Requests	Rate limit exceeded.
500 Internal Server Error	A server-side error occurred.

Headers

Request Content-Type: not applicable (no body on GET).
Response Content-Type: application/json

Throttling & Rate Limits

Limit: 10,000 requests per day per IP address.

Endpoint 1

GET People

Fetches information about the people resource — individual persons or characters within the Star Wars universe (e.g., Luke Skywalker, Leia Organa).

Resource: /people
Methods: GET
Base URL: https://swapi.dev/api/
End Point: /?page=1
Request URL: https://swapi.dev/api/people/
Example URL: https://swapi.dev/api/people/?page=1

Query Parameters

Parameter	Mandatory/Optional	Data Type	Values	Description
page	Optional	Integer	1 to 82	The page number to retrieve. Default is 1.

Response Parameters

Parameter	Child	Data Type	Description
count		Integer	Total number of results. Example 82.
next		String	URL of the next page. Example: https://swapi.dev/api/people/?page=2
previous		String	URL of the previous page. null if none.
results	name	String	The name of this person.
	height	String	Height of the person in centimetres.
	hair_color	String	Hair color. 'unknown' or 'n/a' if not applicable.
	skin_color	String	Skin color of this person.
	eye_color	String	Eye color. 'unknown' or 'n/a' if not applicable.
	birth_year	String	Birth year using BBY / ABY (Battle of Yavin) standard.
	gender	String	'male', 'female', 'unknown', or 'n/a'.
	homeworld	String	URL of the homeworld planet resource.
	films	Array	Film resource URLs the person has appeared in.
	species	Array	Species resource URLs the person belongs to.
	vehicles	Array	Vehicle resource URLs the person has piloted.
	starships	Array	Starship resource URLs the person has piloted.
	created	String	ISO 8601 creation timestamp.
	edited	String	ISO 8601 last-edited timestamp.
	url	String	Hypermedia URL of this resource.

Example Response

{
  "count": 82,
  "next": "https://swapi.dev/api/people/?page=2",
  "previous": null,
  "results": [
    {
      "name": "Luke Skywalker",
      "height": "172",
      "mass": "77",
      "hair_color": "blond",
      "skin_color": "fair",
      "eye_color": "blue",
      "birth_year": "19BBY",
      "gender": "male",
      "homeworld": "https://swapi.dev/api/planets/1/",
      "films": [
        "https://swapi.dev/api/films/1/",
        "https://swapi.dev/api/films/2/"
      ],
      "species": [],
      "vehicles": ["https://swapi.dev/api/vehicles/14/"],
      "starships": ["https://swapi.dev/api/starships/12/"],
      "created": "2014-12-09T13:50:51.644000Z",
      "edited": "2014-12-20T21:17:56.891000Z",
      "url": "https://swapi.dev/api/people/1/"
    }
  ]
}

Endpoint 2

GET a Specific Person

Retrieves details for a single character based on their unique ID.

Resource: /people/{:id}/
Methods: GET
Base URL: https://swapi.dev/api/
End Point: /{:id}
Request URL: https://swapi.dev/api/people/{:id}/
Example URL: https://swapi.dev/api/people/10/

Path Parameters

Parameter	Mandatory/Optional	Data Type	Values	Description
:id	Mandatory	Integer	1 to 82	The ID number to retrieve. Example: 10

Example Response

{
  "name": "Obi-Wan Kenobi",
  "height": "182",
  "mass": "77",
  "hair_color": "auburn, white",
  "skin_color": "fair",
  "eye_color": "blue-gray",
  "birth_year": "57BBY",
  "gender": "male",
  "homeworld": "https://swapi.dev/api/planets/20/",
  "films": [
    "https://swapi.dev/api/films/1/",
    "https://swapi.dev/api/films/2/",
    "https://swapi.dev/api/films/3/"
  ],
  "vehicles": ["https://swapi.dev/api/vehicles/38/"],
  "starships": ["https://swapi.dev/api/starships/48/"],
  "created": "2014-12-10T16:16:29.192000Z",
  "edited": "2014-12-20T21:17:50.325000Z",
  "url": "https://swapi.dev/api/people/10/"
}

Authored by Merly Thomas. This sample demonstrates structured API reference authoring — overview, workflow, reference tables, and runnable example payloads.