OpenAPI and client generators

Every Sluurp app describes its own REST API as an OpenAPI 3.1 document. Any tool that reads OpenAPI can use it to make a typed client in your language, show interactive docs, or test the API.

The document

GET /api/openapi.json is made from the app as it is right now:

• every collection’s endpoints, with its fields as a schema and its rules written out;
• signing in, signing up and refreshing a token;
• the app’s own functions, with their method and rule.

Because it’s made on each request, it can’t drift from the app. Add a field, and the document has it at once.

It describes every collection, so only a superuser may read it. Sign in as one, and pass the token:

$ TOKEN=$(curl -s http://localhost:8090/api/collections/_superusers/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity":"you@example.com","password":"…"}' | jq -r .token)

$ curl -s http://localhost:8090/api/openapi.json -H "Authorization: Bearer $TOKEN" > openapi.json

Or open the admin’s API screen and download openapi.json from there. The same screen lets you try any endpoint as yourself, and copy the request as curl.

Save the file in your project and generate from it. Fetch it again when the schema changes, since generated code only knows what was there when you made it.

Typed clients

TypeScript

For a web app on Sluurp you rarely need one, since the client knows your collections already. For another codebase, openapi-typescript turns the document into types, and openapi-fetch calls the API with them:

$ npx openapi-typescript openapi.json -o src/sluurp-api.d.ts

import createClient from "openapi-fetch";
import type { paths } from "./sluurp-api";

const api = createClient<paths>({ baseUrl: "https://example.com", headers: { Authorization: `Bearer ${token}` } });
const { data } = await api.GET("/api/collections/tasks/records", { params: { query: { filter: "done = false" } } });

Orval and Hey API make clients too, including hooks for TanStack Query.

Other languages

OpenAPI Generator makes clients for more than 50 languages from the same file:

$ npx @openapitools/openapi-generator-cli generate -i openapi.json -g python -o clients/python

Change -g for other languages: go, java, kotlin, swift5, csharp, dart, php, ruby or rust. Tools made for one language are often nicer to use:

Docs to browse

Any OpenAPI viewer shows the file as browsable docs, with a form to try each endpoint: Swagger UI, Redoc or Scalar. To look at it without installing anything, paste the file into editor.swagger.io.

The file describes your whole schema and its rules. Share it with people who build against your API, but don’t publish it where anyone can read it.

Tools that import it

• Postman, Insomnia, Bruno and Hoppscotch import the file as a collection of requests.
• Schemathesis reads it to test every endpoint with generated input, looking for crashes and answers that don’t match the schema.
• AI assistants and agents can be given the file, so they know every endpoint and field of your app.

Related

• The REST API: every endpoint, filters, files and errors.
• Browser client: the typed JavaScript client for apps on Sluurp.