swapi.build

# SWAPI.build

A free, open-source Star Wars API serving data about People, Films, Planets, Species, Starships, and Vehicles. Built with [Quarkus](https://quarkus.io/) and [GraalVM](https://www.graalvm.org/) for instant startup, minimal memory footprint, and out-of-the-box performance.

Inspired by the original [SWAPI](https://swapi.dev/) (created by Paul Hallett, maintained by Juriy Bura), this project was born out of the need for a Star Wars API that **never goes offline**. If you've ever had a live demo break because a third-party API went down, you know why this exists.

## Quick Start

**Prerequisites:** Java 25 and Maven (or use the included Maven Wrapper).

```bash
cd swapi-app
./mvnw quarkus:dev
```

The API and frontend will be available at **http://localhost:5432**.

## API Endpoints

Base path: `/api`

| Resource | List All | By ID | Random | Search |
|----------|----------|-------|--------|--------|
| People | `GET /api/people` | `GET /api/people/:id` | `GET /api/people/random` | `GET /api/people?search=name` |
| Films | `GET /api/films` | `GET /api/films/:id` | `GET /api/films/random` | `GET /api/films?search=title` |
| Planets | `GET /api/planets` | `GET /api/planets/:id` | `GET /api/planets/random` | `GET /api/planets?search=name` |
| Species | `GET /api/species` | `GET /api/species/:id` | `GET /api/species/random` | `GET /api/species?search=name` |
| Starships | `GET /api/starships` | `GET /api/starships/:id` | `GET /api/starships/random` | `GET /api/starships?search=name` |
| Vehicles | `GET /api/vehicles` | `GET /api/vehicles/:id` | `GET /api/vehicles/random` | `GET /api/vehicles?search=name` |

Ids are the record ids from each entity's `url` field (for films, `1` = A New Hope).
Successful responses return `200`; unknown or non-numeric ids return `404`.

All responses are JSON. Example:

```bash
curl http://localhost:5432/api/people/1
```

## OpenAPI

The full API contract is served at [`/openapi.json`](https://swapi.build/openapi.json)
(OpenAPI 3.x, generated from the code — always in sync). The
[documentation page](https://swapi.build/docs) renders from it, including a
"try it" for every endpoint. Generate a client with, e.g.:

    npx @openapitools/openapi-generator-cli generate -i https://swapi.build/openapi.json -g typescript-fetch

## MCP Server

swapi.build is also a remote [MCP](https://modelcontextprotocol.io) server over
**Streamable HTTP**. Any Streamable HTTP client works: the stateless `2026-07-28`
revision sends self-contained requests, and earlier revisions negotiate a session
through `initialize` — both are served on the same endpoint. The legacy HTTP+SSE
transport (`2024-11-05`) is not supported. First-party, read-only, no authentication:

```
https://swapi.build/mcp
```

Full setup guides: **[swapi.build/docs/mcp](https://swapi.build/docs/mcp)**

| Tool | Arguments | Returns |
|------|-----------|---------|
| `sw_list` | `resource` | All entities of a resource |
| `sw_get` | `resource`, `id` | One entity by id |
| `sw_random` | `resource` | A random entity |
| `sw_search` | `resource`, `query` | Name/title substring match |

`resource` is one of `PEOPLE`, `FILMS`, `PLANETS`, `SPECIES`, `STARSHIPS`, `VEHICLES`.
Ids are the record ids from each entity's `url` field (for `FILMS`, `1` = A New Hope).

**Caching:** Quarkiverse MCP Server 2.0.0 emits the required `ttlMs: 0` and
`cacheScope: "public"` fields on stateless discovery and tool-list responses.
Zero TTL means immediately stale; no positive freshness period is configured.
Its [cache hints](https://github.com/quarkiverse/quarkus-mcp-server/blob/2.0.0/docs/modules/ROOT/pages/release-notes.adoc)
apply to discovery, list methods and `resources/read`, **not `tools/call`**.
The Star Wars data here is exposed through tools, so tool-result caching is not
enabled, including for `sw_random`. REST/edge caching is a separate mechanism.

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add --transport http swapi-build https://swapi.build/mcp
```

Or share via `.mcp.json` at the repo root:

```json
{
  "mcpServers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}
```

Verify: `claude mcp list` → `swapi-build ✔ Connected`.
</details>

<details>
<summary><strong>Claude Desktop &amp; claude.ai</strong></summary>

Settings → Connectors → **Add custom connector** → name `swapi-build`, URL
`https://swapi.build/mcp`. No authentication needed. Verify in any chat via the **+** menu → Connectors.
</details>

<details>
<summary><strong>OpenAI Codex</strong></summary>

```bash
codex mcp add swapi-build --url https://swapi.build/mcp
```

Or in `~/.codex/config.toml` (shared by CLI, IDE extension and ChatGPT desktop):

```toml
[mcp_servers.swapi-build]
url = "https://swapi.build/mcp"
```

Verify: `codex mcp list`.
</details>

<details>
<summary><strong>GitHub Copilot (VS Code)</strong></summary>

`.vscode/mcp.json` (top-level key is `servers`):

```json
{
  "servers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}
```

Or Command Palette → **MCP: Add Server**. Verify via the **Configure Tools** button in Copilot Chat.
On Business/Enterprise, the "MCP servers in Copilot" org policy must be enabled.
</details>

<details>
<summary><strong>IBM Bob</strong></summary>

`~/.bob/settings/mcp_settings.json` (global) or `.bob/mcp.json` (project):

```json
{
  "mcpServers": {
    "swapi-build": {
      "type": "streamable-http",
      "url": "https://swapi.build/mcp",
      "disabled": false
    }
  }
}
```

Or Bob panel → MCP tab → **Edit Global MCP**. Bob detects the tools automatically.
</details>

> The server scales to zero when idle — if the very first connection attempt fails, retry once
> (the native binary starts in tens of milliseconds; the platform may take a bit longer to
> provision the container; subsequent calls are fast, whether your client is stateless or
> session-based).

## WebMCP in the browser (experimental)

The website exposes `sw_list`, `sw_get`, `sw_search` and `sw_random` through
WebMCP. Names and arguments match the remote MCP tools, including uppercase
resource names. Each browser tool updates the visible explorer and returns
complete records in a JSON result with `ok`, `data`, `resource` and `path`.
The browser result envelope differs from the remote MCP transport.

Use a compatible browser with WebMCP enabled and the `document.modelContext`
API. The [setup and demonstration guide](https://swapi.build/docs/webmcp)
explains the inspector, example calls and cancellation behavior. When the API
is unavailable, the site works normally. No model API key or AI runtime is
embedded in the site. The JavaScript is bundled by Quinoa and runs in the
browser, including when served by the Quarkus native executable.

## Client examples

- [`examples/java/langchain4j-mcp-client`](examples/java/langchain4j-mcp-client) — ask
  questions in natural language; the tools come from the MCP server above, so the example
  defines none.
- [`examples/java/quarkus-rest-client`](examples/java/quarkus-rest-client) — call the REST
  API from Java with a typed client.

## Project Structure

```
swapi-app/
  Dockerfile.vercel           # Native container image used by Vercel deploys
  src/main/
    java/com/eldermoraes/     # Backend (Quarkus + Jakarta REST)
      film/                   # Film model, service, resource
      people/                 # People model, service, resource
      planet/                 # Planet model, service, resource
      specie/                 # Specie model, service, resource
      starship/               # Starship model, service, resource
      vehicle/                # Vehicle model, service, resource
      mcp/                    # MCP server tools (sw_list, sw_get, sw_random, sw_search)
      SWObject.java           # Base model class
      SWService.java          # Service interface
      ApiResource.java        # Root /api endpoint
      ApplicationPath.java    # Jakarta REST base path (/api)
    resources/
      data/                   # Static JSON data files
      application.properties  # Quarkus configuration
    webui/                    # Frontend (TypeScript + Vite)
      src/
        api.ts                # API client with request management
        main.ts               # SPA router
        pages/                # Page renderers (home, resource, docs, mcp, about, privacy, terms)
        json-highlight.ts     # JSON syntax highlighting for result panels
        style.css             # Site styles
        types.ts              # TypeScript interfaces for API resources
        constants.ts          # Shared resource metadata
        utils.ts              # Shared utilities (escapeHtml)
  src/test/
    java/com/eldermoraes/     # Regression suite (REST contracts, MCP tools, forwarded headers)
```

Each backend domain (film, people, planet, etc.) follows the same pattern:

- **Model** (e.g., `Film.java`): POJO with `@RegisterForReflection` for native image support
- **Service** (e.g., `FilmService.java`): loads data from JSON at startup, caches in memory
- **Resource** (e.g., `FilmResource.java`): Jakarta REST controller with `@RunOnVirtualThread`

## Build

```bash
cd swapi-app

# Development mode (live reload)
./mvnw quarkus:dev

# Production JAR
./mvnw package
java -jar target/quarkus-app/quarkus-run.jar

# Native executable (requires GraalVM or container build)
./mvnw package -Dnative
./mvnw package -Dnative -Dquarkus.native.container-build=true
```

The frontend is automatically built and bundled by [Quinoa](https://docs.quarkiverse.io/quarkus-quinoa/dev/index.html) during the Maven build. No separate `npm` step is needed.

## Deployment

The app runs on [Vercel](https://vercel.com/) as a native (GraalVM/Mandrel) container image, built from `swapi-app/Dockerfile.vercel`. DNS is managed on Cloudflare (DNS-only records pointing to Vercel). Deploys are done with `npx vercel deploy --prod` from the `swapi-app/` directory.

## T