Skip to main content

Quick Tutorial: JSON:API Specification

Introduction​

JSON:API is a specification for building APIs in JSON. It provides a consistent structure for requests and responses, which helps in reducing the amount of work needed to develop and maintain APIs. This tutorial will guide you through the basics of JSON:API using job-related examples.

SmartyMeet follows the JSON:API specification to ensure that our API is consistent, easy to use, and scalable. By adhering to this specification, we can provide a robust and reliable interface for our users.

Basic Concepts​

JSON:API is designed to optimize HTTP request and response handling. Here are the core concepts:

  • Resources: Primary entities represented in JSON:API.
  • Document: A structured JSON object that describes the response format.
  • Relationships: Links between resources.

Document Structure​

A JSON:API document MUST contain at least one of the following top-level members:

  • data: The primary data (a single resource or an array of resources).
  • errors: An array of error objects.
  • meta: A meta object that contains non-standard meta-information.

Optional members include:

  • links: Links related to the primary data.
  • included: Related resources included in the response.

Example​

{
  "data": {
    "type": "jobs",
    "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
    "attributes": {
      "title": "Software Engineer",
      "status": "published"
    },
    "relationships": {
      "company": {
        "data": { "type": "companies", "id": "c398c4f5ccf440828fb578344ca77c1d" }
      }
    }
  }
}

Resources​

Resources in JSON:API are represented as JSON objects with the following members:

  • type: The type of the resource.
  • id: The unique identifier of the resource.
  • attributes: The resource attributes.
  • relationships: Links to related resources.
  • links: A links object related to the resource.
  • meta: A meta object that contains non-standard meta-information.

Example​

{
  "type": "jobs",
  "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
  "attributes": {
    "title": "Software Engineer",
    "status": "published"
  }
}

Relationships​

Relationships define how resources are related to each other. They are represented in the relationships member of a resource object.

Example​

{
  "type": "jobs",
  "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
  "relationships": {
    "company": {
      "data": { "type": "companies", "id": "3:c398c4f5ccf440828fb578344ca77c1d" }
    }
  }
}

Fetching Data​

Fetching a Single Resource​

To fetch a single resource, perform a GET request to the resource URL.

Request:

GET /v1/jobs/fb57e929cc354ed3b66ffe234b7ce61b-3

Response:

{
  "data": {
    "type": "jobs",
    "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
    "attributes": {
      "title": "Software Engineer",
      "status": "published"
    },
    "relationships": {
      "company": {
        "data": { "type": "companies", "id": "2:c398c4f5ccf440828fb578344ca77c1d" }
      }
    }
  }
}

Fetching Multiple Resources​

To fetch multiple resources, perform a GET request to the resource collection URL.

Request:

GET /v1/jobs

Response:

{
  "data": [
    {
      "type": "jobs",
      "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
      "attributes": {
        "title": "Software Engineer",
        "status": "published"
      }
    },
    {
      "type": "jobs",
      "id": "4:40712512cca3446e99565598abff58d8",
      "attributes": {
        "title": "Data Scientist",
        "status": "draft"
      }
    }
  ]
}

Creating, Updating, and Deleting Resources​

Creating a Resource​

To create a resource, perform a POST request with the resource object in the body.

Request:

POST /v1/jobs

Request Body:

{
  "data": {
    "type": "jobs",
    "attributes": {
      "title": "Backend Developer",
      "status": "draft"
    }
  }
}

Response:

{
  "data": {
    "type": "jobs",
    "id": "2:adeec52c457845a49868a2c5013e5f0e",
    "attributes": {
      "title": "Backend Developer",
      "status": "draft"
    }
  }
}

Updating a Resource​

To update a resource, perform a PATCH request with the updated resource object in the body.

Request:

PATCH /v1/jobs/fb57e929cc354ed3b66ffe234b7ce61b-3

Request Body:

{
  "data": {
    "type": "jobs",
    "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
    "attributes": {
      "title": "Senior Software Engineer",
      "status": "published"
    }
  }
}

Response:

{
  "data": {
    "type": "jobs",
    "id": "fb57e929cc354ed3b66ffe234b7ce61b-3",
    "attributes": {
      "title": "Senior Software Engineer",
      "status": "published"
    }
  }
}

Deleting a Resource​

To delete a resource, perform a DELETE request to the resource URL.

Request:

DELETE /v1/jobs/fb57e929cc354ed3b66ffe234b7ce61b-3

Response:

204 No Content

Error Handling​

Errors are represented as an array of error objects in the errors member of the document.

Example​

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "The requested job could not be found."
    }
  ]
}

Conclusion​

This quick tutorial covers the basics of the JSON:API specification using job-related examples. By following these guidelines, you can create a consistent and efficient API that adheres to the JSON:API standards. For more detailed information, refer to the JSON:API official documentation.