JsonApi4j

Choose Your Stack

Spring Boot Auto-configuration, zero boilerplate. Add one dependency and go. Quarkus Native Quarkus extension with CDI integration and build-time processing. Jakarta Servlet API Direct integration — no framework required, just the Servlet API.

Why JsonApi4j

One standard. Every service. No more API design debates — just consistent, spec-compliant endpoints out of the box.

JSON:API Compliant

Purpose-built around the JSON:API specification — predictable request/response format and processing rules.

Auto-Generated OpenAPI

Always-in-sync API documentation derived from the same metadata used at runtime. Powerful customization capabilities. Exposed as JSON or YAML via a dedicated endpoint.

Framework Agnostic

Works with Spring Boot, Quarkus, and plain Jakarta Servlet API. Add one dependency and the framework auto-configures itself in your environment.

Under the Hood

Built for engineers who care about what happens between the request and the response.

Pluggable Architecture

Hook into the request pipeline with the visitor-based Plugin System. Ships with Access Control, Sparse Fieldsets, OpenAPI, and Compound Documents plugins.

Compound Documents

Multi-level include queries with parallel batch resolution, built-in caching, and Cache-Control aggregation. Deployable at the application or API Gateway level.

Fine-Grained Access Control

Declarative, annotation-driven authorization — per-field anonymization based on access tier, OAuth2 scopes, and resource ownership. No changes to core logic.

Minimal Boilerplate

Define resources, relationships, and operations — the framework automatically generates JSON:API documents, pagination links, error responses, and many more.

Persistence/Data Source Agnostic

No JPA or Hibernate required. Works with SQL, NoSQL, REST clients, in-memory stores, or any data source you bring.

Parallel Execution

Relationship resolution, compound document fetching, and batch operations run concurrently. Supports virtual threads (Project Loom) for maximum throughput.

Built to Pair With Your AI Agent

An official Claude Code plugin and a cross-tool AGENTS.md — so your AI assistant builds spec-compliant APIs the framework's way. Learn more →

Official Claude Code Plugin

Install the plugin and your AI agent instantly knows how to design resources, relationships, operations, compound documents, validation, and tests — right in your own project.

Learn More

Works With Any AI Tool

A committed AGENTS.md gives Claude Code, Cursor, GitHub Copilot, and Codex the same project context — build commands, conventions, and module map.

Knows the Idioms

Not generic Java scaffolding — agents follow framework patterns: lightweight relationship refs, N+1-safe includes, cd.mapping, and the right testing setup.

Request Processing Pipeline

Every incoming API request flows through a well-defined processing pipeline — from data retrieval through relationship resolution to final document composition. At each stage, registered plugins can inspect, mutate, or short-circuit the request using the Visitor pattern.

Quick Example

Define a resource and an operation — that’s all it takes to expose a fully compliant JSON:API endpoint:

@JsonApiResource(resourceType = "users")
public class UserResource implements Resource<UserDbEntity> {

    @Override
    public String resolveResourceId(UserDbEntity dto) {
        return dto.getId();
    }

    @Override
    public UserAttributes resolveAttributes(UserDbEntity dto) {
        return new UserAttributes(dto.getFullName(), dto.getEmail());
    }
}

@JsonApiResourceOperation(resource = UserResource.class)
public class UserOperations implements ResourceOperations<UserDbEntity> {

    @Override
    public PaginationAwareResponse<UserDbEntity> readPage(JsonApiRequest request) {
        return PaginationAwareResponse.limitOffsetAware(
                userDb.readAll(request.getLimit(), request.getOffset()),
                userDb.total()
        );
    }
}

GET /users →

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "fullName": "John Doe",
        "email": "john@example.com"
      },
      "links": {
        "self": "/users/1"
      }
    }
  ],
  "links": {
    "self": "/users?page[offset]=0&page[limit]=20",
    "next": "/users?page[offset]=20&page[limit]=20"
  },
  "meta": {
    "pagination.totalItems": 26
  }
}