JSON API

JSON:API

Our API follows the JSON:API Specification↗ to maintain a consistent and predictable structure in both requests and responses. By adhering to this format, we ensure each endpoint behaves in a standardized way, making it easier to parse data, handle errors, and navigate relationships between resources.

Core Implementation Details

  1. Resources
    • We treat each entity (e.g., users, posts, comments) as a “resource.”
    • Resources in our API have:
      • A type (e.g., "posts")
      • A unique id
      • attributes (the data of the resource)
      • relationships (references to other resources)
  2. Relationships
    • When a resource references others (for instance, a post has many comments), we include a relationships object that describes these links.
    • The relationship can contain identifiers, links, and/or metadata about how the resources connect.
  3. Compound Documents
    • To avoid multiple network requests, we often provide “included” resources in the same response.
    • For example, retrieving a post can also include its associated comments or author information.
  4. Error Handling
    • We return errors in a standardized JSON:API format, which can include fields like status, title, and detail.
    • This makes client-side error handling more straightforward.
  5. Filtering, Pagination & Sorting

    For details on filtering, pagination, and sorting, see our dedicated guide.

    • Our API uses conventional JSON:API query parameters for filtering (e.g., filter[author]=123), paginating (e.g., page[size]=25&page[number]=2), and sorting (e.g., sort=-created_at).

Example Response

Below is an example of how we might return a post with its author included:

{
  "data": [
    {
      "type": "posts",
      "id": "1",
      "attributes": {
        "title": "Hello World",
        "content": "This is my first post."
      },
      "relationships": {
        "author": {
          "data": { "type": "users", "id": "10" }
        }
      },
      "links": {
        "self": "https://api.example.com/posts/1"
      }
    }
  ],
  "included": [
    {
      "type": "users",
      "id": "10",
      "attributes": {
        "username": "JaneDoe",
        "email": "jane@example.com"
      },
      "links": {
        "self": "https://api.example.com/users/10"
      }
    }
  ]
}
  1. data holds the primary resource(s)—in this case, a list of posts.
  2. relationships points to related resources such as author.
  3. included provides the user resource directly in the same response.
  4. links like self direct you to the resource’s own URL.

Conclusion

Because our API is built on JSON:API principles, you can rely on uniform resource structures, predictable relationships, and consistent error responses across all endpoints. For more details or advanced features, see our specific endpoint documentation or refer to the JSON:API specification.