Base URL

Understanding the base URL is essential for making requests to the Star Wars API. The base URL differs between environments.

Production

Live API

Use this URL for production apps

https://sw-next-api.vercel.app

Development

Local Server

Use when running locally

http://localhost:3000

API Versioning

All endpoints are prefixed with /api/v1/ for version control.

Current Version

All endpoints in this documentation use version 1

/api/v1/people/api/v1/films/api/v1/planets/api/v1/species/api/v1/starships/api/v1/vehicles

Constructing URLs

URL Structure

Build complete API URLs in 4 steps

Base URL

https://sw-next-api.vercel.app

Version prefix

/api/v1/

Resource path

people

Query parameters (optional)

?isJedi=true&expand=homeworld

Complete URL:

https://sw-next-api.vercel.app/api/v1/people?isJedi=true&expand=homeworld

Quick Examples

Get a list of all people (paginated)

Request

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

Client Configuration

TypeScript/JavaScript

Create a reusable API configuration:

// config/api.ts
export const API_CONFIG = {
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'https://sw-next-api.vercel.app',
  version: 'v1',
} as const;

export function getApiUrl(path: string): string {
  return `${API_CONFIG.baseURL}/api/${API_CONFIG.version}${path}`;
}

// Usage
const url = getApiUrl('/people?isJedi=true');
// Result: https://sw-next-api.vercel.app/api/v1/people?isJedi=true

Environment Variables

Environment Setup

Configure base URL per environment

Local development (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:3000

Production (.env.production)

NEXT_PUBLIC_API_URL=https://sw-next-api.vercel.app

Use in your code

const BASE_URL = process.env.NEXT_PUBLIC_API_URL;
const response = await fetch(`${BASE_URL}/api/v1/people`);

Fetch Wrapper

Create a wrapper for cleaner, reusable API calls:

// lib/api.ts
const BASE_URL = 'https://sw-next-api.vercel.app/api/v1';

export async function apiRequest<T>(
  endpoint: string,
  options?: RequestInit
): Promise<T> {
  const url = `${BASE_URL}${endpoint}`;

  const response = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    throw new Error(`API request failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage
import { apiRequest } from '@/lib/api';

const people = await apiRequest('/people?isJedi=true');
const luke = await apiRequest('/people/1?expand=homeworld');

Important Notes

CORS

The API supports Cross-Origin Resource Sharing. You can make requests from web apps, browser extensions, and client-side JavaScript without additional configuration.

HTTPS

Production API only accepts HTTPS requests. HTTP requests will be automatically redirected to HTTPS for security.

Rate Limiting

Currently no rate limiting is enforced. Please be respectful: avoid excessive requests, use pagination appropriately, and cache responses when possible.

Testing with cURL

Quick test commands for your terminal:

# Basic request
curl "https://sw-next-api.vercel.app/api/v1/people"

# With query parameters
curl "https://sw-next-api.vercel.app/api/v1/people?isJedi=true&expand=homeworld"

# Pretty print JSON (requires jq)
curl "https://sw-next-api.vercel.app/api/v1/people/1" | jq