JsonApi

Follows the JSON:API specification. Same path-based routing as REST, but uses the JSON:API envelope format with data, relationships, and included sections.

• Spec: jsonapi.org
• MIME: application/vnd.api+json
• Serializer: JsonApiSerializer
• Routing: Path-based (/models, /models/:id)

Setup

import crate.protocols.jsonApi.policy;

auto crateRouter = router.crateSetup!JsonApi;
crateRouter.add(userCrate);

Generated Endpoints

The six standard CRUD endpoints, plus relationship management:

Method	Path	Operation	Status
GET	/users	List all	200
GET	/users/:id	Get one	200
POST	/users	Create	201
PUT	/users/:id	Replace	200
PATCH	/users/:id	Update fields	200
DELETE	/users/:id	Delete	204
GET	/users/:id/relationships/:rel	Get relationship	200
PATCH	/users/:id/relationships/:rel	Update relationship	200
POST	/users/:id/relationships/:rel	Add to relationship	200
DELETE	/users/:id/relationships/:rel	Remove from relationship	200

Creates return 201 with a Location header pointing to the new resource.

Request Headers

Clients must send Accept: application/vnd.api+json.

Response Format

{
  "data": {
    "type": "users",
    "id": "abc123",
    "attributes": {
      "name": "Alice",
      "email": "alice@example.com"
    },
    "relationships": {
      "team": {
        "data": { "type": "teams", "id": "xyz789" }
      }
    }
  }
}

Supported JSON:API Features

• Sparse fieldsets (?fields[type]=field1,field2)
• Compound documents / inclusion (?include=relationship)
• Pagination (?page[number]=X&page[size]=Y) with first, last, prev, next links
• Sorting (?sort=field,-otherField) — prefix with - for descending
• Relationship endpoints (GET/PATCH/POST/DELETE)
• Proper resource identifier format (type, id, attributes, relationships)
• ETag / If-None-Match conditional requests (304 Not Modified)
• Query parameter validation — unknown parameters are rejected

Not Yet Supported

• Filtering: No ?filter parameter (use middleware)
• Bulk operations: No batch operations
• JSON:API extensions: No extension mechanism

Custom Base URL

auto crateRouter = router.crateSetup!(JsonApiPolicy!(PolicyConfig("/api/v1")));