skills.rest
DeepSpaceCartel
DeepSpaceCartelOFFICIAL
Explore all skills by this author →
WebsiteGitHub

jsonapi

Design and review JSON:API v1.1 request and response formats for REST APIs.

Updated Sep 9, 2026
Search Tags:#error handling#api design#rest api#response format#jsonapi#content negotiation#compound documents
One-click install
npx skills add https://github.com/DeepSpaceCartel/skills --skill jsonapi-deepspacecartel
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: jsonapi
Source: https://github.com/DeepSpaceCartel/skills/tree/main/skills/jsonapi
Command: npx skills add https://github.com/DeepSpaceCartel/skills --skill jsonapi-deepspacecartel

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Designing a REST API response format from scratch leads to inconsistent document shapes, ad-hoc query parameters, and error responses that clients cannot parse reliably. This Skill encodes the JSON:API v1.1 specification so endpoints follow one predictable structure that any compliant client can consume without per-endpoint documentation. ## Core Features & Use Cases - Document Structure Guidance: Defines the top-level document shape, resource objects, relationships, resource linkage, compound documents with full linkage, and member-name rules. - Query Parameter Conventions: Covers the reserved parameter families — include, fields (sparse fieldsets), sort, page, and filter — plus rules for extension and implementation-specific parameters. - CRUD Semantics and Errors: Specifies correct status codes for creating, updating, and deleting resources and relationships, content negotiation with ext/profile media-type parameters, and structured error objects. - Use Case: When reviewing an endpoint that returns related data, verify the response is a valid compound document where every included resource is reachable via relationship linkage from the primary data. ## Quick Start Review my GET /articles endpoint response and tell me whether it complies with the JSON:API v1.1 document structure and include parameter rules.

Frequently Asked Questions about jsonapi

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a JSON:API response document?▼

A JSON:API document must contain data, errors, or meta at the top level, with data and errors never coexisting. Each resource object requires type and id, served with the Content-Type application/vnd.api+json.

How do I include related resources in a JSON:API response?▼

Use the include query parameter with comma-separated relationship paths, such as ?include=comments.author. The response must be a compound document where every included resource is reachable via relationship linkage from the primary data.

What HTTP status code should a JSON:API POST return?▼

Return 201 Created with the created resource when the server assigned anything beyond the request, such as a generated id. Return 204 No Content if the resource was created exactly as sent, or 409 Conflict for a duplicate client-generated id.

Does JSON:API support sparse fieldsets and filtering?▼

Yes, sparse fieldsets use fields[TYPE]=name1,name2 to restrict returned fields per resource type. The filter parameter family is reserved by the spec, but the filtering strategy and syntax are left to each implementation.

Why does a JSON:API PATCH ignore a missing field instead of clearing it?▼

The spec defines an omitted field in a PATCH body as meaning leave the current value unchanged, not set it to null. Treating a missing key as clear-this-field is the most common JSON:API PATCH implementation bug.

When should I use JSON:API extensions versus profiles?▼

Use an extension when adding new specification semantics like new document members or query parameters, namespaced with a prefix. Use a profile to standardize usage patterns within the existing spec, such as a timestamp format, without changing wire meaning.

Related Skills

Explore More Software Engineering Skills→
EstomEstom

api-designer

Design REST and GraphQL APIs and generate OpenAPI 3.1 specifications.

Community
Advanced
BrunoAlanBrunoAlan
1

jsonapi

Enforce JSON:API v1.1 compliance in Django REST Framework endpoints.

Community
Intermediate
HZeroxiumHZeroxium

java-error-model

Generate RFC 9457 Problem Details error responses with deterministic exception mappings.

Community
Advanced
objectstack-aiobjectstack-ai
22

objectstack-api

Design ObjectStack runtime REST/GraphQL endpoints with auth, error envelopes, and versioning contracts.

Official
Intermediate