Pre-release — content may change.

Concepts

JSON:API Compliance

Understanding how Wicket implements the JSON:API specification

Wicket's API follows the JSON:API specification, a standard for building APIs in JSON. This ensures consistent, predictable responses across all endpoints.

What is JSON:API?

JSON:API is a specification for how a client should request resources and how a server should respond to those requests. It defines:

  • A consistent structure for requests and responses
  • How to fetch resources and relationships
  • How to create, update, and delete resources
  • Error formatting
  • Pagination, sorting, and filtering patterns

Response Structure

Collection Response

When fetching multiple resources (e.g., GET /people):

{
  "data": [
    {
      "id": "uuid-1",
      "type": "people",
      "attributes": { ... },
      "relationships": { ... }
    },
    {
      "id": "uuid-2",
      "type": "people",
      "attributes": { ... },
      "relationships": { ... }
    }
  ],
  "included": [...],
  "links": {
    "self": "...",
    "first": "...",
    "next": "...",
    "last": "..."
  },
  "meta": {
    "total": 42
  }
}

Single Resource Response

When fetching a single resource (e.g., GET /people/{id}):

{
  "data": {
    "id": "uuid-1",
    "type": "people",
    "attributes": {
      "given_name": "John",
      "family_name": "Smith",
      "email": "jsmith@email.ca",
      "created_at": "2017-07-27T22:21:26.824Z",
      "updated_at": "2017-07-27T22:47:45.129Z"
    },
    "relationships": {
      "emails": {
        "data": [
          { "id": "email-uuid", "type": "emails" }
        ]
      },
      "phones": {
        "data": [
          { "id": "phone-uuid", "type": "phones" }
        ]
      }
    }
  }
}

Resource Objects

Each resource object has four main parts:

1. Resource Identifier

{
  "id": "8f24a446-acac-40bb-8ff3-e6abc051c362",
  "type": "people"
}
  • id: Unique identifier (UUID in Wicket)
  • type: Resource type (people, organizations, etc.)

2. Attributes

{
  "attributes": {
    "given_name": "John",
    "family_name": "Smith",
    "email": "jsmith@email.ca"
  }
}

Resource properties like names, emails, dates, etc.

3. Relationships

{
  "relationships": {
    "emails": {
      "data": [
        { "id": "uuid-1", "type": "emails" }
      ]
    },
    "organization": {
      "data": { "id": "org-uuid", "type": "organizations" }
    }
  }
}

References to related resources with their identifiers.

{
  "links": {
    "self": "/people/uuid-1"
  }
}

URLs for fetching the resource or its relationships.

Use the include parameter to fetch related resources in a single request:

GET /people/uuid-1?include=emails,phones,addresses

Related resources appear in the included array:

{
  "data": {
    "id": "uuid-1",
    "type": "people",
    "relationships": {
      "emails": {
        "data": [{ "id": "email-uuid", "type": "emails" }]
      }
    }
  },
  "included": [
    {
      "id": "email-uuid",
      "type": "emails",
      "attributes": {
        "email_address": "jsmith@email.ca",
        "email_type": "work"
      }
    }
  ]
}

Multiple Includes

Fetch multiple relationship types:

GET /people/uuid-1?include=emails,phones,addresses,connections

Nested Includes

Some endpoints support nested includes using dot notation:

GET /connections?include=to,from,to.emails

This fetches connections with their related people and those people's emails.

Sparse Fieldsets

Request only specific fields to reduce payload size:

GET /people?fields[people]=given_name,family_name,email

Response includes only requested fields:

{
  "data": [
    {
      "id": "uuid-1",
      "type": "people",
      "attributes": {
        "given_name": "John",
        "family_name": "Smith",
        "email": "jsmith@email.ca"
      }
    }
  ]
}

Sparse Fields for Relationships

Specify fields for included resources:

GET /people?include=emails&fields[people]=given_name,family_name&fields[emails]=email_address

Compound Documents

Compound documents combine primary data with related resources, reducing the number of HTTP requests needed.

Example - fetching a person with their emails and phones:

GET /people/uuid-1?include=emails,phones
{
  "data": {
    "id": "uuid-1",
    "type": "people",
    "attributes": { ... },
    "relationships": {
      "emails": {
        "data": [
          { "id": "email-1", "type": "emails" },
          { "id": "email-2", "type": "emails" }
        ]
      },
      "phones": {
        "data": [
          { "id": "phone-1", "type": "phones" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "email-1",
      "type": "emails",
      "attributes": {
        "email_address": "work@example.com"
      }
    },
    {
      "id": "email-2",
      "type": "emails",
      "attributes": {
        "email_address": "personal@example.com"
      }
    },
    {
      "id": "phone-1",
      "type": "phones",
      "attributes": {
        "phone_number": "+1-555-123-4567"
      }
    }
  ]
}

Error Responses

Errors follow JSON:API format:

{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "title": "Validation Failed",
      "detail": "Given name can't be blank",
      "source": {
        "pointer": "/data/attributes/given_name"
      }
    }
  ]
}

Each error object includes:

  • status: HTTP status code as a string
  • code: Application-specific error code
  • title: Short, human-readable summary
  • detail: Detailed error message
  • source (optional): Pointer to the error source

Multiple Validation Errors

{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "title": "Validation Failed",
      "detail": "Given name can't be blank",
      "source": { "pointer": "/data/attributes/given_name" }
    },
    {
      "status": "422",
      "code": "validation_error",
      "title": "Validation Failed",
      "detail": "Email is invalid",
      "source": { "pointer": "/data/attributes/email" }
    }
  ]
}

Creating Resources

POST requests follow JSON:API format:

POST /people
Content-Type: application/vnd.api+json
{
  "data": {
    "type": "people",
    "attributes": {
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "jdoe@example.com"
    }
  }
}

Response (201 Created):

{
  "data": {
    "id": "new-uuid",
    "type": "people",
    "attributes": {
      "uuid": "new-uuid",
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "jdoe@example.com",
      "created_at": "2024-01-17T12:00:00.000Z",
      "updated_at": "2024-01-17T12:00:00.000Z"
    }
  }
}

Updating Resources

PATCH requests update existing resources:

PATCH /people/uuid-1
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "uuid-1",
    "type": "people",
    "attributes": {
      "job_title": "Senior Developer"
    }
  }
}

Include only the fields you want to update. Unchanged fields will remain the same.

Deleting Resources

DELETE requests remove resources:

DELETE /people/uuid-1

Response: 204 No Content (success, no response body)

Content Type

All requests and responses use the JSON:API media type:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Benefits of JSON:API

  1. Consistency: Same patterns across all endpoints
  2. Efficiency: Include related resources to reduce requests
  3. Flexibility: Sparse fieldsets reduce payload size
  4. Error Handling: Standardized error format
  5. Tooling: Many client libraries support JSON:API

JSON:API Client Libraries

Consider using a JSON:API client library for your language:

See the full list at jsonapi.org/implementations.

On this page