Skip to content

toedter/spring-hateoas-jsonapi

Repository files navigation

build Quality Gate Status coverage maven-central Apache 2.0

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

{
  "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
    }
  }
}
{
    "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."
        }
    ]
}