milesbehind / spring-hateoas-jsonapi

A JSON:API media type implementation for Spring HATEOAS

JSON:API for Spring HATEOAS

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

This project is work in progress, please stay tuned.

Documentation

Here you find the documentation for the latest release and the current snapshot:

0.8.0	Reference Documentation	API Documentation
0.9.0-SNAPSHOT	Reference Documentation	API Documentation

Integration in 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>0.8.0</version>
</dependency>

Gradle:

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

The latest published snapshot version is 0.9.0-SNAPSHOT. If you want to try it out, please make sure to add https://oss.sonatype.org/content/repositories/snapshots/ as 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 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?page[number]=0&page[size]=1",
    "next": "http://localhost:8080/api/movies?page[number]=1&page[size]=1",
    "last": "http://localhost:8080/api/movies?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