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.
4. Links (Optional)
{
"links": {
"self": "/people/uuid-1"
}
}URLs for fetching the resource or its relationships.
Including Related Resources
Use the include parameter to fetch related resources in a single request:
GET /people/uuid-1?include=emails,phones,addressesRelated 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,connectionsNested Includes
Some endpoints support nested includes using dot notation:
GET /connections?include=to,from,to.emailsThis 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,emailResponse 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_addressCompound 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 stringcode: Application-specific error codetitle: Short, human-readable summarydetail: Detailed error messagesource(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-1Response: 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+jsonBenefits of JSON:API
- Consistency: Same patterns across all endpoints
- Efficiency: Include related resources to reduce requests
- Flexibility: Sparse fieldsets reduce payload size
- Error Handling: Standardized error format
- Tooling: Many client libraries support JSON:API
JSON:API Client Libraries
Consider using a JSON:API client library for your language:
- JavaScript: devour, jsonapi-client
- Python: jsonapi-client
- Ruby: jsonapi-rb
- PHP: art4/json-api-client
See the full list at jsonapi.org/implementations.