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 latest release and the current snapshot:

1.4.0	Reference Documentation	API Documentation
1.4.1-SNAPSHOT	Reference Documentation	API Documentation

Integration with your Backends

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

Maven:

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

Gradle:

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

The latest published snapshot version is 1.4.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 8 or later JDK 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) rendered result is:

{
  "jsonapi": {
    "version": "1.0"
  },
  "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[movies]=title,year,rating,directors&include=directors&page[number]=0&page[size]=1",
     "next": "http://localhost:8080/api/movies?fields[movies]=title,year,rating,directors&include=directors&page[number]=1&page[size]=1",
     "last": "http://localhost:8080/api/movies?fields[movies]=title,year,rating,directors&include=directors&page[number]=249&page[size]=1"
  },
  "meta": {
    "page": {
      "number": 0,
      "size": 1,
      "totalPages": 250,
      "totalElements": 250
    }
  }
}

License

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