:doctype: book image:https://github.com/toedter/spring-hateoas-jsonapi/workflows/Build/badge.svg["build", link="https://github.com/toedter/spring-hateoas-jsonapi/actions"] image:https://sonarcloud.io/api/project_badges/measure?project=toedter_spring-hateoas-jsonapi&metric=alert_status["Quality Gate Status", link="https://sonarcloud.io/project/overview?id=toedter_spring-hateoas-jsonapi"] image:https://codecov.io/gh/toedter/spring-hateoas-jsonapi/branch/main/graph/badge.svg["coverage", link="https://codecov.io/gh/toedter/spring-hateoas-jsonapi"] image:https://img.shields.io/maven-central/v/com.toedter/spring-hateoas-jsonapi?color=green["maven-central", link="https://central.sonatype.com/artifact/com.toedter/spring-hateoas-jsonapi/2.1.0/versions"] image:https://img.shields.io/badge/License-Apache%202.0-blue.svg["Apache 2.0", link="https://opensource.org/licenses/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 | https://toedter.github.io/spring-hateoas-jsonapi/2.1.0/reference/[Reference Documentation] | https://toedter.github.io/spring-hateoas-jsonapi/2.1.0/api/[API Documentation] | 2.1.1-SNAPSHOT | https://toedter.github.io/spring-hateoas-jsonapi/snapshot/reference/[Reference Documentation] | https://toedter.github.io/spring-hateoas-jsonapi/snapshot/api/[API Documentation] | 1.6.0 | https://toedter.github.io/spring-hateoas-jsonapi/1.6.0/reference/[Reference Documentation] | https://toedter.github.io/spring-hateoas-jsonapi/1.6.0/api/[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: [source] implementation 'com.toedter:spring-hateoas-jsonapi:2.1.0'

Maven: [source,xml]

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 link:++http://localhost:8080/api/movies?page[number]=0&page[size]=1&include=directors&fields[movies]=title,year,rating,directors++[++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:

[source,json] { "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 link:++http://localhost:8080/api/movies/1000[http://localhost:8080/api/movies/1000] in your Web browser to get a JSON:API compliant error response:

[source,json] { "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