json-api/json-api
Json Api
JSON API is a set of industry standards for RESTful APIs that defines uniform protocols for resource serialization, error responses, and query parameters. It provides a specification for request and response payloads in JSON-based APIs to ensure consistency across endpoints.
The specification focuses on reducing network requests through a structured resource serialization format and a standardized mechanism for embedding related resources into a single response. It utilizes a custom JSON media type for content negotiation and supports the definition of custom profiles to provide specialized information beyond the base technical standard.
The standard covers resource management by mapping HTTP methods to lifecycle operations and employs a uniform error object structure for predictable failure handling. It also includes a standardized query protocol for filtering, sorting, and paginating resource collections.
Features
- Resource Serialization Formats - Implements a structured JSON format that separates primary data from relationships and metadata to minimize network requests.
- REST API Specifications - Defines a consistent format for requests and responses in REST APIs to ensure consistency across endpoints.
- Client-Requested Resource Inclusions - Enables bundling linked data into a single response when explicitly requested via query parameters to minimize network requests.
- Resource Serialization Formats - Provides a structured JSON format that separates primary resource data, relationships, and metadata for consistent client parsing.
- Compound Document Embeddings - Includes related resources alongside primary data in a single response using a reserved includes parameter.
- HTTP Query Protocols - Provides a standardized method for filtering, sorting, and paginating resource collections using uniform query parameters.
- Resource Type-ID Pairs - Ensures every resource object carries a mandatory type and id pair for consistent referencing and traversal.
- Query Parameter Filters - Provides standardized query parameters for filtering, sorting, and paginating resource collections at API endpoints.
- API Error Handling Patterns - Implements standardized patterns for returning uniform error objects with unique identifiers for predictable failure management.
- Structured Error Responses - Implements a uniform error object format containing unique identifiers, status codes, and detail fields.
- Declarative Data Fetching - Reduces network round trips by embedding related resources into a single JSON response.
- Uniform Error Objects - Returns failures in a consistent object format containing a unique identifier and a descriptive detail.
- Resource-Relationship Separations - Structures JSON payloads by separating core resource attributes from their relationships and metadata.
- RESTful Resource Management - Performs create, read, update, and delete operations on data collections using standard HTTP methods and uniform JSON structures.
- HTTP Verb Lifecycle Mapping - Maps standard HTTP methods like GET, POST, PATCH, and DELETE directly to resource lifecycle operations.
- HTTP Verb Lifecycle Mapping - Maps standard HTTP methods directly to create, read, update, and delete operations.
- Response Structure Standardization - Provides a standardized structure for API error objects, ensuring consistent failure responses across all endpoints.
- REST API Specifications - Defines a standard format for request and response payloads in JSON-based REST APIs to ensure consistency.
- API Profile Definitions - Allows the definition of custom profiles to deliver specialized information beyond the base technical specification.
- Content Negotiation - Utilizes a custom JSON media type with profile parameters for server and client content negotiation.
