JSON:API for Spring HATEOAS

This is an implementation of the application/vnd.api+json (JSON:API) media type for Spring HATEOAS. The goal is to use existing Spring HATEOAS representation models to serialize and deserialize them according to the JSON:API specification (see https://jsonapi.org/).

While an advanced usage example is included in this project, you can find more examples at https://github.com/toedter/spring-hateoas-jsonapi-examples.

Documentation

The following table contains links to the documentation for each release and the current snapshot:

3.0.1	Reference Documentation	API Documentation
3.0.2-SNAPSHOT	Reference Documentation	API Documentation
2.2.0	Reference Documentation	API Documentation
1.6.0	Reference Documentation	API Documentation

Version Matrix

Before adding this library to your application, you need to determine which version to use. The following table shows the compatibility matrix:

JSON:API for Spring HATEOAS	Java	JSON:API	Spring HATEOAS	Spring Boot	Spring Framework	Jackson
1.x.x	11	1.0	1.5.x	2.7.x	5.3.x	2.x
2.x.x	17	1.1	2.x.x	3.x.x	6.x.x	2.x
3.x.x	17	1.1	3.x.x	4.x.x	7.x.x	3.x

Note	Version 3 is the first version based on Spring Boot 4 and Jackson 3. This includes breaking changes from the Jackson 2 to Jackson 3 migration. The last version supporting Spring Boot 3 is 2.2.0.

Warning

Version 3 removes all deprecated APIs from version 2.x.x. Specifically, withJsonApiVersionRendered() and withObjectMapperCustomizer() have been removed and replaced with withJsonApiObject() and withMapperCustomizer() respectively. See the Migration Guide for details.

Integration with Your Backend

To enable the JSON:API media type, simply add this module as a dependency to your project.

Gradle:

implementation 'com.toedter:spring-hateoas-jsonapi:3.0.1'

Maven:

<dependency>
    <groupId>com.toedter</groupId>
    <artifactId>spring-hateoas-jsonapi</artifactId>
    <version>3.0.1</version>
</dependency>

The latest published snapshot version is 3.0.2-SNAPSHOT. To use it, add https://central.sonatype.com/repository/maven-snapshots/ as a repository in your Maven or Gradle configuration.

Running the Example

• Ensure Java 17 JDK (or later) is installed

• Clone this Git repository and navigate to the spring-hateoas-jsonapi directory

• Run ./gradlew bootrun (or gradlew bootrun on Windows)

• Open http://localhost:8080/api/movies?page[number]=0&page[size]=1&include=directors&fields[movies]=title,year,rating,directors in your web browser. The response (pretty-printed) will be:

{
  "jsonapi": {
    "version": "1.1"
  },
  "data": [
    {
      "id": "1",
      "type": "movies",
      "attributes": {
        "title": "The Shawshank Redemption",
        "year": 1994,
        "rating": 9.3
      },
      "relationships": {
        "directors": {
          "data": [
            {
              "id": "2",
              "type": "directors"
            }
          ],
          "links": {
            "self": "http://localhost:8080/api/movies/1/relationships/directors",
            "related": "http://localhost:8080/api/movies/1/directors"
          }
        }
      },
      "links": {
        "self": "http://localhost:8080/api/movies/1"
      }
    }
  ],
  "included": [
    {
      "id": "2",
      "type": "directors",
      "attributes": {
        "name": "Frank Darabont"
      }
    }
  ],
  "links": {
     "self": "http://localhost:8080/api/movies?fields%5Bmovies%5D=title,year,rating,directors&include=directors&page%5Bnumber%5D=0&page%5Bsize%5D=1",
     "next": "http://localhost:8080/api/movies?fields%5Bmovies%5D=title,year,rating,directors&include=directors&page%5Bnumber%5D=1&page%5Bsize%5D=1",
     "last": "http://localhost:8080/api/movies?fields%5Bmovies%5D=title,year,rating,directors&include=directors&page%5Bnumber%5D=249&page%5Bsize%5D=1"
  },
  "meta": {
    "page": {
      "size": 1,
      "totalElements": 250,
      "totalPages": 250,
      "number": 0
    }
  }
}

• Open http://localhost:8080/api/movies/1000 in your web browser to receive a JSON:API compliant error response:

{
    "errors": [
        {
            "id": "9d29c51d-ca50-40b6-addc-9c130b0e44a6",
            "status": "404",
            "code": "xrn:err:platform:resourceNotFound",
            "title": "Resource Not Found",
            "detail": "Resource of type 'movies' with id '1000' not found."
        }
    ]
}

License

Apache 2.0, see https://opensource.org/licenses/Apache-2.0