Star Wars API

BFF Edition

Star Wars API

Backend for Frontend Edition

A modern, frontend-friendly Star Wars API with aggregation, expand, filtering and pagination. Educational backend for frontend developers.

Based on SWAPI with extended metadata

Why This API Exists

Most Star Wars APIs are data-oriented, not UI-oriented. This API uses the Backend for Frontend (BFF) pattern to eliminate waterfall requests.

Traditional API

5+ requests
Multiple requests to display one character
GET /people/1           # Luke Skywalker
GET /planets/1          # Tatooine
GET /films/1            # A New Hope
GET /films/2            # Empire Strikes Back
GET /films/3            # Return of the Jedi

This API

1 request
All data in a single request with expand
Request
GET https://sw-next-api.vercel.app/api/v1/people/1?expand=homeworld,films

1 request includes:

  • Character details
  • Homeworld data
  • All films with full info

Core Features

Controlled Expansion

Query exactly what you need with expand parameter
GET https://sw-next-api.vercel.app/api/v1/people/1
GET https://sw-next-api.vercel.app/api/v1/people/1?expand=homeworld
GET https://sw-next-api.vercel.app/api/v1/people/1?expand=films.characters

Smart Pagination

Built-in pagination with page and limit parameters
Request
GET https://sw-next-api.vercel.app/api/v1/people?page=2&limit=10
{
  "page": 2,
  "limit": 10,
  "total": 82,
  "pages": 9,
  "results": [...]
}

Search & Filter

Search by name and filter by attributes
GET https://sw-next-api.vercel.app/api/v1/people?search=luke
GET https://sw-next-api.vercel.app/api/v1/people?gender=female
GET https://sw-next-api.vercel.app/api/v1/people?sort=-name

API Endpoints

GET

People

/api/v1/people

Characters from the Star Wars universe

GET

Films

/api/v1/films

All Star Wars films

GET

Planets

/api/v1/planets

Planets and locations

GET

Species

/api/v1/species

Species and alien races

GET

Starships

/api/v1/starships

Starships and space vessels

GET

Vehicles

/api/v1/vehicles

Ground and atmospheric vehicles

Normalized & Type-Safe Responses

Unlike SWAPI, this API returns normalized, camelCase data with TypeScript-ready structure

Minimal Projections (default)

Related entities return as minimal objects with entityId, id (slug), and name/title

camelCase naming

All fields use camelCase (heightCm, birthYearBBY) with proper types (numbers, not strings)

Base URL

Local development: http://localhost:3000
Production: https://sw-next-api.vercel.app

Add base URL to all requests: https://sw-next-api.vercel.app/api/v1/people/1

Examples

Basic Request

Returns normalized data with minimal projections for related entities

Request
GET https://sw-next-api.vercel.app/api/v1/people/1
Response
{
  "entityId": 1,
  "id": "luke-skywalker",
  "name": "Luke Skywalker",
  "heightCm": 172,
  "massKg": 77,
  "birthYearBBY": -19,
  "gender": "male",
  "homeworld": {
    "entityId": 1,
    "id": "tatooine",
    "name": "Tatooine"
  },
  "films": [
    { "entityId": 1, "id": "a-new-hope", "title": "A New Hope", "episode": 4 },
    { "entityId": 2, "id": "the-empire-strikes-back", "title": "The Empire Strikes Back", "episode": 5 },
    { "entityId": 3, "id": "return-of-the-jedi", "title": "Return of the Jedi", "episode": 6 },
    { "entityId": 6, "id": "revenge-of-the-sith", "title": "Revenge of the Sith", "episode": 3 }
  ],
  "species": [],
  "vehicles": [
    { "entityId": 14, "id": "snowspeeder", "name": "Snowspeeder" },
    { "entityId": 30, "id": "imperial-speeder-bike", "name": "Imperial Speeder Bike" }
  ],
  "starships": [
    { "entityId": 12, "id": "x-wing", "name": "X-wing" },
    { "entityId": 22, "id": "imperial-shuttle", "name": "Imperial shuttle" }
  ],
  "meta": {
    "isForceUser": true,
    "isJedi": true,
    "isSith": false,
    "faction": "rebels"
  }
}

Extended Metadata

Unlike SWAPI, this API includes additional metadata for richer queries and filtering

People Extensions

Force abilities and faction affiliations
Force-Sensitive

Track Force users with isForceUser, isJedi, isSith

Factions

Filter by faction: rebels, empire, republic, separatists, civilian

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

Starships Extensions

Military classification and faction ownership
Military Status

Classify ships as military or civilian with is_military

Faction Ownership

Track which faction operates each vessel

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

Find Imperial military ships