jsonapi4j

JsonApi4j — JSON:API Framework for Java

A lightweight Java framework for building REST APIs compliant with the JSON:API specification. Works with Spring Boot, Quarkus, and the Jakarta Servlet API.

Features

📋 Spec-Compliant by Default

Full JSON:API compliance out of the box — resources, relationships, compound documents, pagination, sparse fieldsets, error handling, and links. No shortcuts, no partial implementations.

🔌 Works With Your Stack

First-class support for Spring Boot, Quarkus, and plain Jakarta Servlet API. One dependency, zero configuration — the framework auto-configures itself.

🗄️ Bring Your Own Data Source

No JPA or ORM required. Use SQL, NoSQL, REST clients, in-memory stores — anything that returns data. The framework never touches your persistence layer.

🧩 Plugin System

Extend the request processing pipeline without modifying core logic. Build your own plugins or use the built-in ones:

• Access Control — per-field authorization via annotations, OAuth2 scopes, resource ownership
• OpenAPI — auto-generated spec from your domain model
• Sparse Fieldsets — fields[type] filtering on the server
• Compound Documents — multi-level include with parallel resolution

⚡ Built for Performance

Concurrent relationship resolution, parallel compound document fetching, and support for virtual threads (Project Loom). Designed for production throughput from day one.

Why JsonApi4j?

🏛️ One Standard, Every Service

Every service ships with the same request/response format, the same pagination model, the same error structure — enforced by the framework, not by design reviews. Whether you're building a new microservice or standardizing an existing API layer, JsonApi4j gives your team an enforceable shared contract across Spring Boot, Quarkus, or plain Servlet.

🚀 Ship Faster

Define your resources and operations — routing, serialization, pagination links, error handling, and documentation are generated automatically. Less plumbing, more domain logic.

Quick Start

1. Add dependency

The framework modules are published to Maven Central.

Stack	Artifact
Spring Boot	pro.api4:jsonapi4j-rest-springboot
Quarkus	pro.api4:jsonapi4j-rest-quarkus
Servlet API	pro.api4:jsonapi4j-rest

<dependency>
  <groupId>pro.api4</groupId>
  <artifactId>jsonapi4j-rest-springboot</artifactId>
  <version>${jsonapi4j.version}</version>
</dependency>

2. Define a resource

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

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

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

3. Implement an operation

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

    private final UserDb userDb;

    public UserOperations(UserDb userDb) {
        this.userDb = userDb;
    }

    @Override
    public PaginationAwareResponse<UserDbEntity> readPage(JsonApiRequest request) {
        var page = userDb.readAllUsers(request.getCursor());
        return PaginationAwareResponse.cursorAware(page.getEntities(), page.getCursor());
    }
}

4. Get a JSON:API response

GET /users