JSON:API

JSON:API is a specification for building APIs in JSON. All the APIs exposed by Connhex Resources follow this standard.

JSON:API example

Taking the previous example of a device resource, let's see how it would be represented in JSON:API response. If a device is represented by the following interface:

Assuming we perform a GET request to api/resources/devices:

{
  "jsonapi": { "version": "1.0" },
  "meta": { "count": 2 },
  "links": {
    "self": "api/resources/devices/5b5ebc9b-6fbc-40ca-83b2-020b8969bf65,7889beca-a845-40e4-a9c5-1fca3957eff2"
  },
  "data": [
    {
      "type": "devices",
      "id": "5b5ebc9b-6fbc-40ca-83b2-020b8969bf65",
      "attributes": {
        "serial": "VV-KOK5DLPS06T1H3",
        "type": "valve",
        "connhex-id": "b6f9bb6d-6ffb-4a5c-8539-d79aa292a640",
        "metadata": "",
        "created-at": "2022-01-25T08:25:08.633Z",
        "updated-at": null,
        "deleted-at": null
      },
      "relationships": {
        "tags": {
          "links": {
            "self": "api/resources/devices/5b5ebc9b-6fbc-40ca-83b2-020b8969bf65/relationships/tags",
            "related": "api/resources/devices/5b5ebc9b-6fbc-40ca-83b2-020b8969bf65/tags"
          },
          "data": [
            { "type": "tags", "id": "59065461-a379-46ed-86ae-295f7f7d6198" }
          ]
        },
        "plant": {
          "links": {
            "self": "api/resources/devices/5b5ebc9b-6fbc-40ca-83b2-020b8969bf65/relationships/plant",
            "related": "api/resources/devices/5b5ebc9b-6fbc-40ca-83b2-020b8969bf65/plant"
          },
          "data": null
        }
      },
      "links": {
        "self": "api/resources/devices/5b5ebc9b-6fbc-40ca-83b2-020b8969bf65"
      }
    },
    {
      "type": "devices",
      "id": "7889beca-a845-40e4-a9c5-1fca3957eff2",
      "attributes": {
        "serial": "VV-900632343E1D16",
        "type": "valve",
        "connhex-id": "1789c65e-0720-4c8a-ae21-b39f13fd0b3d",
        "metadata": "crio",
        "created-at": null,
        "updated-at": null,
        "deleted-at": null
      },
      "relationships": {
        "tags": {
          "links": {
            "self": "api/resources/devices/7889beca-a845-40e4-a9c5-1fca3957eff2/relationships/tags",
            "related": "api/resources/devices/7889beca-a845-40e4-a9c5-1fca3957eff2/tags"
          },
          "data": []
        },
        "plant": {
          "links": {
            "self": "api/resources/devices/7889beca-a845-40e4-a9c5-1fca3957eff2/relationships/plant",
            "related": "api/resources/devices/7889beca-a845-40e4-a9c5-1fca3957eff2/plant"
          },
          "data": {
            "type": "plants",
            "id": "4629391f-9346-4357-b213-f77e050abb57"
          }
        }
      },
      "links": {
        "self": "api/resources/devices/7889beca-a845-40e4-a9c5-1fca3957eff2"
      }
    }
  ]
}

Here's a brief description of the fields:

• jsonapi contains the version of the JSON:API specification used.
• meta contains metadata about the response. It always contains the number of resources returned.
• links contain links to the resource itself, and to the relationships.
• data contains the actual data of the response. It is an array of resources.
• relationships contain references to other resources. In this case, the plant relationship is a reference to a plant resource, and the tags relationship is a reference to many tag resources.
• attributes contains the actual data of the resource. It is an object with the fields of the resource.
• connhex-id manages the relationship between the resource and the Connhex device. It is a read-only field, and it is automatically populated by the Connhex Resources API. We automatically convert keys between camelCase and kebab-case.

Relationship expansion

By default, only the ids of the related resources are returned. This allows for a more compact response, and more performant queries. However, if you need to get the full data of the related resources, you can use the include query parameter.

In the example above, just pass something like {include: "tags"} or {include: "plant,tags"} and the related resources will be included in the response.