Consider implementing JSON:API spec

[nathanuphoff]

When I first opened the api docs it appears the responses are formatted according to the JSON:API specification, only after inspecting the data property it turned out to not be the case. The likeness is really close though, even upon further inspection in the source code it looks like its already akin to a JSON:API formatter (in /app/serializers).

This is an actual example response from the docs.

{
  "data": [
    {
      "id": 1,
      "name": "Plantae",
      "slug": "plantae",
      "links": {
        "self": "/api/v1/kingdoms/plantae"
      }
    }
  ],
  "links": {
      "self": "/api/v1/kingdoms",
      "first": "/api/v1/kingdoms?page=1",
      "last": "/api/v1/kingdoms?page=1"
  },
  "meta": {
    "total": 1
  }
}

and this is how it would look like with JSON:API:

{
  "data": [
    {
      "id": 1,
      "type": "kingdom",
      "attributes": {
        "name": "Plantae",
        "slug": "plantae",
      },
      "links": {
        "self": "/api/v1/kingdoms/plantae"
      }
    }
  ],
  "links": {
      "self": "/api/v1/kingdoms",
      "first": "/api/v1/kingdoms?page=1",
      "last": "/api/v1/kingdoms?page=1"
  },
  "meta": {
    "total": 1
  }
}

The most notable changes are a 'resource type' property, and the attributes being wrapped in an 'attributes' field (if there's relationship fields in a response, these will be wrapped in a 'relationships' object similarly).

The advantage of JSON:API is that it allows the usage of sparse fieldsets and compound documents, both aimed towards flexibility and reducing/optimizing the payload, allowing to pick and choose resources, much like GraphQL.

Another great benefit is the predictability of each response, and on top of that the plethora of tooling available to parse JSON:API documents. The nice thing about sparsefield sets and compound documents is that they are optional, allowing for an iterative upgrade path, with only (relatively) small changes to start out with.