JSON:API for Spring HATEOAS

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

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

Documentation

Here you find the documentation for the releases and the current snapshot:

2.1.0	Reference Documentation	API Documentation
2.1.1-SNAPSHOT	Reference Documentation	API Documentation
1.6.0	Reference Documentation	API Documentation

Version Matrix

If you want to add the library to your app, the first step is to determine the version of the library you should use.

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

Integration with your Backends

To enable the JSON:API media type you just need to add this module as a dependency to your project.

Gradle:

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

Maven:

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

The latest published snapshot version is 2.1.1-SNAPSHOT. If you want to try it out, please make sure to add https://oss.sonatype.org/content/repositories/snapshots/ as a repository to your Maven or Gradle configuration.

Running the Example

• Make sure Java 17 JDK (or later) is installed

• Clone this Git repository and cd into spring-hateoas-jsonapi

• Invoke ./gradlew bootrun (just gradlew 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 (pretty-printed) response is:

{
  "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 get 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