REST API Documentation

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/rest-api-documentation/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Developers can discover and use AstroBaaS REST APIs with clear OpenAPI documentation, code examples, and API reference. Documentation is generated from the OpenAPI spec and kept in sync automatically. Core owns the API documentation; this is infrastructure, not a paid feature.

The problem

Developers cannot use the API because there is no documentation. They reverse-engineer endpoints by inspecting requests or reading source code, which is error-prone and slow.

What it does

• OpenAPI 3.0 spec: complete API definition is machine-readable (as YAML or JSON)
• Interactive API reference: web UI lets developers explore endpoints, try requests, see responses
• Code examples: API reference includes curl, JavaScript, Python code snippets
• Authentication docs: clear instructions for API key creation, bearer token usage, session cookies
• Error codes: all HTTP status codes (200, 400, 401, 403, 404, 500) documented with examples
• Rate limiting: documented rate limits per endpoint
• Webhook docs: webhook events are documented with payload examples
• Search: developers can search for endpoint by name (e.g., ‘create order’)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Tutorial documentation: we provide API reference only; step-by-step guides (build a plugin, integrate Stripe) are separate (not included in this feature).
• SDKs: we do not build SDKs (JavaScript, Python, PHP); developers use auto-generated clients (OpenAPI generator).
• Change log: API version history is documented elsewhere (not in this feature).

Data model

No new schema. OpenAPI spec is generated from code and served as static files.

API

• GET /api/docs (redirects to OpenAPI UI)
• GET /api/docs/openapi.json (OpenAPI spec in JSON)
• GET /api/docs/openapi.yaml (OpenAPI spec in YAML)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

No admin UI needed. Developers access /api/docs from public web.

The seam — why this is core

Core owns the OpenAPI spec generation, documentation UI, and code examples. No paid seam; this is infrastructure.

Core owns the interface + honest OpenAPI/Swagger docs; API documentation is infrastructure, not a per-country obligation or support commitment.

Dependencies

• REST API subsystem (existing; all endpoints are documented)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• OpenAPI spec is complete (all routes, parameters, responses, error codes included)
• API reference UI is accessible at /api/docs with searchable endpoint list
• Endpoint documentation includes: description, request parameters, request body example, response example, error codes
• Code examples show curl, JavaScript (fetch), Python (requests) for each endpoint
• Authentication section documents API key creation, bearer token format, session cookie usage
• All HTTP status codes (200, 201, 400, 401, 403, 404, 409, 500) are documented with error response example
• Rate limiting docs show: 100 requests/min per IP, 1000 requests/min per API key
• OpenAPI spec is valid (can be imported into Postman, Insomnia, or third-party tools)

Risks

If OpenAPI spec is manual and not auto-generated, it diverges from actual implementation over time. If code examples are wrong (copy-paste errors), developers follow broken examples. If error codes are missing, developers don’t know how to handle failures. If authentication docs are unclear, developers use wrong method and get 401 errors. If rate limits are undocumented, developers hit limits without warning. If spec is not machine-readable, third-party tools cannot generate client code.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.