Arabica JSON API Contract #

This directory is the interface contract between three parallel work streams in the SvelteKit SPA migration:

• Stream A (Go JSON API) implements these endpoints.
• Stream B (SvelteKit frontend) consumes them.
• Stream C (testing) generates contract tests from these shapes.

Each file documents the request/response shapes for a domain area. When adding or changing an endpoint, update the spec here first, then implement.

The non-JSON homepage Open Graph contract covers crawler metadata and the public preview image endpoint.

Conventions #

• All JSON endpoints return Content-Type: application/json; charset=utf-8.

• Mutations (POST/PUT/DELETE) are CSRF-protected via the CrossOriginProtection middleware. The SvelteKit frontend sends the same cookies/forms it does today.

• Error responses use a stable envelope with an appropriate HTTP status:

  {
    "error": "Human-readable safe message",
    "code": "stable_machine_code"
  }
  

  Validation responses may also include fields, a map from field name to a safe validation message. Machine codes are low-cardinality values such as authentication_required, session_expired, permission_denied, not_found, validation_failed, invalid_request, conflict, rate_limited, service_unavailable, and internal_error.

• Error messages must not expose dependency errors, stack traces, tokens, session identifiers, or other internal details.

• Timestamps are RFC 3339 strings.

• AT-URIs are full at://did:plc:.../collection/rkey strings.

• Pagination uses cursor strings; an empty next_cursor means no more pages.

Existing JSON Endpoints (already working) #

These endpoints already return JSON and need no changes:

Phase 1 Endpoints (implemented) #

These endpoints were added in Phase 1 of the SvelteKit migration:

Endpoints to Add (Phase 1) #

See the migration plan (docs/plans/2026-07-08-sveltekit-migration.md) for the full list and priority order. Each endpoint's shape is documented in its own file as it is implemented:

• feed.md — GET /api/feed (JSON feed items) [done]
• entities.md — GET /api/{entity}/{actor}/{id} (entity view data) [done]
• brews.md — POST /brews, PUT /brews/{id} (brew mutations) [done]
• manage.md — GET /api/manage (records + stats) [done]
• brew_list.md — GET /api/brews (paginated brew list) [done]
• profile.md — GET /api/profile/{actor} (profile data bundle) [done]
• notifications.md — GET /api/notifications [done]
• explore.md — GET /api/explore [done]
• social.md — likes, comments, reports (JSON mutations) [done]
• settings.md — GET /api/settings, settings mutations [done]
• onboarding.md — GET /api/onboarding, incomplete records [done]
• backlinks.md — GET /api/{entity}/{actor}/{id}/backlinks [done]
• admin.md — moderation admin endpoints [done]
• signup.md — GET /api/signup/categories (PDS provider catalog) [done]