Core Concepts

Master the essential features that make this API flexible and powerful. All concepts work together and can be combined in a single request.

Quick Navigation

Pagination

Navigate through large datasets

Expansion

Include related data in one request

Filtering

Find exactly what you need

Sorting

Order results your way

Pagination

Control how many results you get per page and navigate through large datasets efficiently.

Parameters

page

Current page number (default: 1, min: 1)

limit

Items per page (default: 10, min: 1, max: 100)

Basic Usage

Default (first page, 10 items):

Request

GET https://sw-next-api.vercel.app/api/v1/people

Navigate pages with custom limit:

Request

GET https://sw-next-api.vercel.app/api/v1/people?page=2&limit=20

Response Format

Every paginated response includes metadata:

{
  "page": 2,           // Current page number
  "limit": 20,         // Items per page
  "total": 82,         // Total items across all pages
  "pages": 5,          // Total number of pages
  "results": [...]     // Array of items for current page
}

Expansion

Include related data in a single request instead of making multiple requests. Maximum depth: 2 levels.

Basic Expansion

Expand one relation:

Request

GET https://sw-next-api.vercel.app/api/v1/people/1?expand=homeworld

Expand multiple relations:

Request

GET https://sw-next-api.vercel.app/api/v1/people/1?expand=homeworld,films

Nested Expansion

Expand relations of relations (up to 2 levels deep):

Request

GET https://sw-next-api.vercel.app/api/v1/people/1?expand=films.characters

This expands films, and within each film, expands the characters array.

Available Expansions by Resource

People

homeworld - Home planet

films - Films appeared in

species - Species

vehicles - Vehicles piloted

starships - Starships piloted

Films

characters - Characters in film

planets - Planets featured

species - Species featured

vehicles - Vehicles featured

starships - Starships featured

Planets

residents - Planet residents

films - Films featured in

Species

homeworld - Homeworld planet

people - Members of species

films - Films featured in

Filtering

Filter results by any field to find exactly what you need.

Search by Name

Search across name/title fields:

Request

GET https://sw-next-api.vercel.app/api/v1/people?search=skywalker

Filter by Standard Fields

Filter by any field in the response:

Request

GET https://sw-next-api.vercel.app/api/v1/people?gender=female

Filter by Metadata

Use custom metadata fields for advanced filtering:

People metadata:

GET https://sw-next-api.vercel.app/api/v1/people?isJedi=true
GET https://sw-next-api.vercel.app/api/v1/people?isForceUser=true
GET https://sw-next-api.vercel.app/api/v1/people?faction=rebels

Starships metadata:

GET https://sw-next-api.vercel.app/api/v1/starships?is_military=true
GET https://sw-next-api.vercel.app/api/v1/starships?faction=empire

Combine Multiple Filters

All filters work together:

Request

GET https://sw-next-api.vercel.app/api/v1/people?gender=female&faction=rebels&isForceUser=true

Tip

Filters are case-insensitive and work with partial matches for text fields. Boolean filters (isJedi, isForceUser) accept "true" or "false".

Sorting

Sort results by any field in ascending or descending order.

Ascending Order

Sort alphabetically or numerically:

GET https://sw-next-api.vercel.app/api/v1/people?sort=name
GET https://sw-next-api.vercel.app/api/v1/people?sort=heightCm

Descending Order

Use - prefix for reverse order:

GET https://sw-next-api.vercel.app/api/v1/people?sort=-name
GET https://sw-next-api.vercel.app/api/v1/people?sort=-heightCm

Common Sort Examples

People

sort=name - Alphabetical A-Z

sort=-name - Alphabetical Z-A

sort=heightCm - Shortest first

sort=-heightCm - Tallest first

sort=birthYearBBY - Oldest first

Films

sort=episode - Episode order

sort=-episode - Reverse episode

sort=release_year - Release order

sort=title - Alphabetical

Combining Everything

The real power comes from combining all these features in a single request:

Request

GET https://sw-next-api.vercel.app/api/v1/people?search=skywalker&isJedi=true&sort=name&page=1&limit=5&expand=homeworld,films

This request:

🔍 Searches for "skywalker"
✅ Filters for Jedi only
⬆️ Sorts alphabetically by name
📄 Returns 5 results on page 1
🚀 Expands homeworld and films data

Best Practice

Start simple and add complexity as needed. Begin with basic pagination, then add filtering, sorting, and expansion only when your UI requires it.