JSON:API — Latest Specification (v1.0)

Latest specification (v1.0)

state

This page shows the latest released version of JSON:API, which is currently version 1.0. The new version of JSON:API will always be used, will never be deleted, and only add policies that are backward compatible. Can be in our discuss The district made a supplement.

If you find errors in the specification text, or if you have written an implementation, please GitHub repository Open questions or pull requests to inform us.

introduce

JSON:API is a specification about how the client should request to obtain or modify resources and how the server should respond to these requests.

JSON: the API is designed to minimize the number of requests and the amount of data transferred between the client and the server. This efficiency is achieved without affecting readability, flexibility or discoverability.

JSON:API requires JSON:API media type ( application/vnd.api+json )To exchange data.

appointment

The keywords "must", "must not", "request", "should", "should", "should", "should", "should not", "recommended", "can" and "optional" in this document are in accordance with RFC 2119 [1] RFC2119 ].

Content negotiation

Customer responsibility

The client must send all JSON:API data in the request document, and its header is content type: application / vnd API + JSON does not take any media type parameters.

A client that accepts a JSON:API media type in its header must specify the media type at least once without any media type parameters.

The client must ignore application / vnd. In the response document header API + JSON # any parameter of the received media type. Content-Type

Server responsibilities

The server must send all JSON:API data in the response document, and its header is content type: application / vnd API + JSON does not take any media type parameters.

If the request specifies a header with any media type parameters, the server must respond with a status code. 415 Unsupported Media TypeContent-Type: application/vnd.api+json

If the header of the request contains a JSON:API media type and all instances of the media type have been modified with the media type parameter, the server must respond with a status code. 406 Not AcceptableAccept

Note: there are content negotiation requirements to allow future versions of this specification to use media type parameters for extended negotiation and version control.

file structure

This section introduces the structure of JSON:API document, which is identified by media type application/vnd.api+json . JSON: API document in JavaScript Object Notation (JSON) [ RFC7159 ].

Although both request and response documents use the same media type, some aspects apply to only one of them. These differences are listed below.

Unless otherwise stated, objects defined in this specification shall not} contain any additional members. Client and server implementations must} ignore members that are not recognized by this specification.

Note: these conditions allow this specification to be developed through additional changes.

top floor

JSON objects must be at the root of every JSON:API request and response that contains data. This object defines the "top level" of a document.

The document must contain at least one of the following top-level members:

• Data: the "main data" of the document
• errors: error object array
• Meta: containing non-standard meta information Meta object.

Member data and errors # cannot coexist in the same document.

A document can contain any of these top-level members:

• jsonapi: object describing the server implementation
• Links: links related to the original data Linked objects.
• included: related to the original data and / or each other Resource object Array ("contained resources").

If the document does not contain a top-level data key, the included member must not appear.

top-level Linked object You can include the following members:

• self: the of generating the current response document Link.
• related: when the master data represents the resource relationship Links to related resources.
• Paging of main data Link.

The "primary data" of a document is a representation of the resource or collection of resources to which the request is directed.

The main data must be:

• single Resource object , single Resource identifier object , or null, for a request for a single resource
• Resource object Array Resource identifier object Array or empty array ([]) for requests targeting a collection of resources

For example, the following main data is a single resource object:

The following main data is a single reference to the same resource Resource identifier object:

The logical collection of resources must be represented as an array, even if it contains only one item or is empty.

Resource object

The "resource object" appears in the JSON:API document to represent the resource.

The resource object must contain at least the following top-level members:

• id
• type

Exception: id this member is not required when the resource object originates from the client and represents a new resource to be created on the server.

In addition, a resource object can contain any of the following top-level members:

• attributes: indicates some data of the resource Attribute object.
• relationships: describes the relationship between resources and other JSON:API resources Relationship object.
• links: a Linked object , including links related to resources.
• meta: one Meta object , which contains non-standard meta information about resources and cannot be expressed as attributes or relationships.

The following is how an article (that is, an article type resource) is displayed in the document:

identify

each Resource object Must contain an id member and a type member. The values of id and type members must be strings.

In a given API, each resource object type and id pair must {identify a unique resource. (a set of URI s controlled by one server, or multiple servers as one server constitute an API.)

The type member is used to describe shared properties and relationships Resource object.

The value of the type member must comply with the Member name Same constraint.

Note: this specification has nothing to do with deformation rules, so the value of type ， can be plural or singular. However, the same value should always be used throughout the implementation.

field

Resource object attribute And relationship Collectively referred to as its“ field".

Resource object The fields of must share a common namespace with each other and with type and id. In other words, a resource cannot have an attribute or relationship with the same name, nor can it have an attribute or relationship id named typeor.

attribute

The value of the attributes key must be an object (an "attribute object"). Members of an attribute object ("attribute") represent information about defining it Information about the resource object.

Property can contain any valid JSON value.

Complex data structures involving JSON objects and arrays are allowed as attribute values. However, any object that constitutes or is contained in an attribute must not contain relationshipsorlinks members, as these members are reserved by this specification for future use.

Although only one foreign key (such as author_id) is usually stored internally with other information to be represented in the resource object, these keys # should not be displayed as attributes.

Note: for more restrictions on this container, see field and Member name.

relationship

The value of the relationships key must be an object ("relationship object"). A member of a relationship object ("relationship") represents a relationship from the resource object that defines it to other resource objects quote.

The relationship can be one-to-one or one to many.

The relationship object must contain at least one of the following:

• links: a that contains at least one of the following Linked object:
  • self: a link to the relationship itself ("relationship link"). This link allows the customer to directly manipulate the relationship. For example, deleting the relationship URL of an authorthrougharticle will disconnect the person from the article without deleting the people resource itself. After successful acquisition, this link returns the information of relevant resources link As its main data. (see Get relationship. )
  • related:Related resource links
• data:Resource linkage
• meta: one Meta object , which contains non-standard meta information about the relationship.

Relationship objects representing one to many relationships can also be included under members paging Link links, as described below. Any in the relationship object paging Links must page relational data, not related resources.

Note: for more restrictions on this container, see field and Member name.

Related resource links

"Related resources link" provides information on In relationLinkedResource object Visit. When obtained, the relevant resource object will be returned as the main data of the response.

For example, the comments of an article relationship You can specify a link , the link returns comments when retrieved through the request A collection of resource objects.GET

If present, the relevant resource link must reference a valid URL, even if the relationship is not currently associated with any target resources. In addition, relevant resource links shall not change due to changes in the content of their relationship.

Resource linkage

compound document Resource links in allow clients to Resource object Link together without going through link Any GET URL access.

Resource links must be represented as one of the following:

• null to empty to one relationship.
• An empty array ([]) for the air to many relationship.
• Single for non empty to one relationships Resource identifier object.
• For non empty to many relationships Resource identifier object Array.

Note: the specification does not give sequential meaning to the resource identifier objects in the many to many relational link array, although the implementation may do so. An array of resource identifier objects can represent ordered or unordered relationships, and the two types can be mixed in a response object.

For example, the following article is associated with an author:

The relationship includes the author link of the relationship itself (allowing the client to directly change the relevant author), the relevant resource link and link information used to obtain the resource object.

Resource link

Each resource object The optional links member in contains information related to the resource link .

If present, the linked object may contain a self link , which identifies the resource represented by the resource object.

The server must respond to the request for the specified URL with a response containing the resource as the primary data.

Resource identifier object

A resource identifier object is an object that identifies a single resource.

The resource identifier object must contain type and id members.

The resource identifier object can also include a meta member whose value is an object containing non-standard meta information Meta object.

Compound file

In order to reduce the number of HTTP requests, the server can allow the response to include related resources and the main resources of the request. Such responses are called "composite documents".

In a composite document, all contained resources must be represented as resources in the top-level member Resource object Array included.

Composite documents need to be "fully linked", which means that each contained resource must be composed of at least one resource in the same document Resource identifier object identifier. These resource identifier objects can be primary data or represent resource links contained in primary or contained resources.

The only exception to the full link requirement is through sparse The field set excludes relational fields that originally contain linked data.

Note: full links ensure that the included resources are linked to the main data (which may be Resource object or Resource identifier object )Or related to each other.

Complete sample document with multiple containment relationships:

One compound document You cannot include more than one for each and pair Resource object.typeid

Note: in a single document, you can think of typeandroid as the only reference to a in another part of the document The compound key of the resource object.

Note: this method ensures that each response returns a specification Resource object , even if the same resource is referenced multiple times.

Meta information

When specified, meta members can be used to contain non-standard meta information. The value of each meta member must be an object ("meta object").

You can specify any member in the meta object.

For example:

link

If specified, links members can be used to represent links. The value of each links member must be an object ("linked object").

Each member of a linked object is a link. The link must be represented as:

• A string containing the URL of the link.
• Objects that can contain the following members ("linked objects"):
  • href: a string containing the link URL.
  • Meta: a meta object that contains non-standard meta information about links.

The following self link is just a URL:

The following related links include a URL and meta information about related resource collections:

Note: you may specify other members for linked objects and linked objects in the future. It is also possible to extend the allowed values of other members (for example, the collection link may support value arrays, while the self link does not).

JSON:API object

JSON:API documentation can contain information about its implementation under top-level jsonapi members. If so, the value of the jsonapi} member must be an object ("jsonapi object"). The JSON API object can {contain a version member whose value is a string indicating the highest supported JSON API version. This object can also contain a meta member whose value is a meta member containing non-standard meta information Meta object.

If the version member does not exist, the client should assume that the server implements at least version 1.0 of the specification.

Note: because the JSON:API only promises to make additional changes, the version string mainly indicates which new features the server may support.

Member name

JSON: all member names used in API documents must be considered case sensitive by the client and server, and they must meet all of the following conditions:

• The member name must contain at least one character.
• Member names must contain only the allowed characters listed below.
• Member names must start and end with "globally allowed characters", as defined below.

In order to easily map member names to URL s, it is recommended that member names be used only RFC 3986 Non reserved URL security characters specified in.

Allowed characters

The following globally allowed characters can be used anywhere in the member name:

• U+0061 to U+007A, "az"
• U+0041 to U+005A, "AZ"
• U+0030 to U+0039, "0-9"
• U+0080 and above (non ASCII Unicode characters; not recommended, not URL safe)

In addition, the following characters are allowed in member names, except the first or last character:

• U+002D hyphen minus sign, "-"
• U+005F low line, ""
• U+0020 SPACE, "" (not recommended, not URL safe)

Reserved characters

The following characters must not be used in member names:

• U+002B plus sign, "+" (for ordering)
• U+002C comma, "," (used as separator between relation paths)
• U+002E period, "." (used as a separator in the relationship path)
• U+005B left square bracket, "[" (for sparse field set)
• U+005D right square bracket, "]" (for sparse field set)
• U+0021 exclamation mark, "!"
• U+0022 quotation marks' "'
• U+0023 numeric symbol, "#"
• U+0024 dollar sign, "$"
• U+0025 percent sign, "%"
• U+0026 and "&"
• U+0027 apostrophe, "'"
• U+0028 left parenthesis, "("
• U+0029 right parenthesis, ")"
• U+002A asterisk, "*"
• U+002F solid, "/"
• U+003A colon, ":"
• U+003B semicolon, ";"
• U+003C less than sign, "<"
• U+003D equal sign, "="
• U+003E greater than sign, ">"
• U+003F question mark, "?"
• U+0040 business address, "@"
• U+005C reverse fixed, "\"
• U+005E cyclic accent, "^"
• U+0060 accent, "`"
• U+007B left brace, "{"
• U+007C vertical line, "|"
• U+007D right curly bracket, "}"
• U+007E wave sign, "~"
• U+007F delete
• U+0000 to U+001F (C0 control)

get data

GET can obtain data, including resources and relationships, by sending a request to the endpoint.

You can further refine the response using the optional features described below.

Get resources

The server must support obtaining resource data for each URL provided:

• Links that are part of the self top-level link object
• Links that are part of the self resource level link object
• A link that is part of a related relational link object

For example, the following request gets a collection of articles:

The following request for an article:

The following request for the author of the article:

respond

200 good

The server must respond to a successful request to obtain a single resource or collection of resources and return a 200 OK response.

The server must respond to a successful request to get a collection of resources that contain Resource object Array or empty array ([]) as the main data of the response document.

For example, a GET request for an article collection might return:

A similar response representing an empty set is:

The server must respond to a successful request to use Resource object Get a single resource or null as the main data provider of the response document.

null is the appropriate response only if the requested URL may correspond to a single resource but does not currently correspond.

Note: for example, consider a request to get a link to a one-to-one related resource. null when the relationship is empty (for example, the link does not correspond to any resource), this request will respond, otherwise it will respond to the request of a single related resource Resource object.

For example, a GET request for a single article might return:

If the author of the above article is missing, the GET request for the relevant resource will return:

404 Not Found

When processing a request to obtain a single resource that does not exist, the server must respond unless the request guarantees that the response is the primary data (as described above). 404 Not Found200 OKnull

Other responses

The server can respond with other HTTP status codes.

The server can contain a message with an error response Error details.

The server must prepare a response and the client must HTTP semantics.

Get relationship

The server must support obtaining relationship data for each relationship URL provided as a link part of the relationship object self. links

For example, the following request for data about article comments:

The following request for data on the author of the article:

respond

200 OK

The server must respond to a successful request to obtain a relationship with the 200 OK response.

The main data in the response document must be consistent with Resource link Match the appropriate values of, as described above Relationship object Described.

top-level Linked object You can include self and related links, as described above Relationship object Described.

For example, a GET request for a URL from a one-to-one relationship link might return:

If the above relationship is empty, GET's request for the same URL will return:

GET a request for a URL from a one to many relationship link may return:

If the above relationship is empty, GET's request for the same URL will return:

404 Not Found

When processing a request to get a non-existent relationship link URL, the server must return. 404 Not Found

Note: this can happen when the parent resource of the relationship does not exist. For example, when / articles/1 does not exist, the request for / articles/1/relationships/tags returns 404 Not Found.

If there is a relationship link URL but the relationship is empty, then # 200 OK # must return, as described above.

Other responses

The server can respond with other HTTP status codes.

The server can contain a message with an error response Error details.

The server must prepare a response and the client must HTTP semantics.

Include related resources

By default, endpoints can return resources related to the original data.

The endpoint can also support the include request parameter to allow the client to customize which related resources should be returned.

If the endpoint does not support the include parameter, it must respond to 400 Bad Request any request that contains it.

If the endpoint supports the include parameter and the client provides it, the server must not compound document The {section of contains unsolicited Resource object. included

The value of the include parameter must be a comma separated list of relationship paths (U + 002C commas, ","). The relationship path is a dot separated (U+002E period, ".") of relationship Name list.

If the server does not recognize the relationship path or does not support containing resources from the path, it must respond with 400 Bad Request.

Note: for example, the relationship path can be comments Author, where {comments is the following articles of the resource object Out And the author is the comments listed under the resource object relationship.

For example, you can request comments through an article:

In order to request resources related to other resources, you can specify a point separated path for each relationship Name:

Note: due to compound document Full links are required (unless the sparse field set excludes relational links), so the intermediate resources in the multipart path must be returned with the leaf node. For example, the response to a request is comments The author should include comments} and each comment of the author.

Note: the server can choose to expose deep nested relationships, such as comments The direct relationship between author and alias, such as comment authors This will allow the client to request / articles / 1? Include = comment authors instead of / articles/1?include=comments.author. By abstracting nested relationships using aliases, the server can still provide complete links in composite documents without including potentially unwanted intermediate resources.

You can request multiple related resources in a comma separated list:

In addition, relevant resources can be requested from the relationship endpoint:

In this case, the main data will be Resource identifier object These objects represent links to article comments, and the complete comments and comment authors will be returned as contained data.

Note: this section applies to any endpoint that uses the primary data response, regardless of the request type. For example, the server can support requests that contain related resources and POST to create resources or relationships.

Sparse field set

The client can request the endpoint to return only specific information in the response on a per type basis by including parameters Field.fields[TYPE]

The value of the fields parameter must be a comma separated (U+002C COMMA, ",") list indicating the name of the field to be returned. A null value means that no fields should be returned.

If a client requests a set of restricted resources of a given resource type Field, endpoint You must not include additional information from a resource object of this type in its response field.

If the client does not specify for the given resource type field Set, the server can send all fields, field subsets or no fields of the resource type.

Note: the example URI above shows the uncoded [and] characters just for ease of reading. In practice, these characters must follow In RFC 3986 Percentage coding of requirements.

Note: this section applies to any endpoint that responds with resources as primary data or containing data, regardless of the type of request. For example, the server can support sparse field sets and POST requests to create resources.

sort

The server can choose to support requests to sort a collection of resources according to one or more criteria (sort fields).

Note: Although recommended, the sorting field does not necessarily correspond to the resource attribute and association name.

Note: it is recommended to use point separation (U+002E FULL-STOP, ".") Sort field to request sorting based on relationship properties. For example, the sort field author Name can be used to request sorting of main data according to the name attribute of the relationship.

The endpoint can support the request to sort the main data using the sort} query parameter. The value of sort ， MUST represents the sort field.

Endpoints can support multiple sort fields by allowing comma separated (U + 002C commas, ",") sort fields. Sort fields should be applied in the specified order.

The sort order of each sort field must be ascending unless it is prefixed with a minus sign (U+002D HYPHEN-MINUS, "-"), in which case it must be descending.

The above example should first return the latest article. Any article created on the same date will be sorted alphabetically in ascending order by its title.

If the server does not support the sort {sort specified in the query parameters, it must return 400 Bad Request.

If the server supports sorting and the client requests sorting sort through query parameters, the server must return the elements of the top-level array of responses sorted according to the specified conditions. If no request parameters are specified, the server can apply the default collation to the top level. data sort

Note: this section applies to any endpoint that responds with a resource collection as the primary data, regardless of the request type.

paging

The server can choose to limit the number of resources returned in the response to respond to a subset of the entire available collection ("pages").

The server can provide a link to traverse the paging data set ("paging link").

Paging links must appear in the linked object corresponding to the collection. To paginate the main data, provide pagination links in the top-level links object. To edit a composite document The contained collection returned in is paged. Please provide a paging link in the corresponding link object.

The following keys must be used for paging links:

• First: first page data
• Last: last page data
• prev: Previous page data
• Next: next page data

The key must either be omitted or have a null value to indicate that a particular link is not available.

The concept of order, as expressed by the naming of paging links, must be consistent with the JSON:API Sorting rules Be consistent.

The page query parameter is reserved for paging. The server and client} should use this key for paging operations.

Note: the JSON:API has nothing to do with the paging policy used by the server. Effective paging strategies include (but are not limited to): page based, offset based and cursor based. The page query parameter can be used as the basis for any of these strategies. For example, a page based policy may use query parameters, such as page[number]and page[size], an offset based policy may use page[offset]and page[limit], and a cursor based policy may use page[cursor].

Note: the above example query parameters use uncoded [and] characters only for ease of reading. In practice, these characters must follow RFC 3986 The requirements in are percentage coded.

Note: this section applies to any endpoint that responds with a resource collection as the primary data, regardless of the request type.

filter

The filter query parameter is reserved for filtering data. The server and client} should use this key for filtering.

Note: the JSON:API has nothing to do with the policies supported by the server. The filter query parameter can be used as the basis for any number of filtering policies.

Create, update, and delete resources

The server can allow the creation of resources of a given type. It also allows you to modify or delete existing resources.

The request must be completely successful or failed (in a single transaction). Partial updates are not allowed.

Note: in the request and response in JSON:API, each This member is required for all resource objects. In some cases, such as when POST accesses an endpoint representing heterogeneous data, type cannot be inferred from the endpoint. However, choosing when needed can be confusing; It's hard to remember when you need it and when you don't. Therefore, type always needs to improve consistency and minimize confusion.

Create resource

You can create a resource by sending a request to the URL that POST represents the resource collection. The request must contain a Resource object As the main data. Resource object Must contain at least one member type.

For example, you can create a new photo using the following request:

If in Resource object If a relationship is provided in a member of relationships, its value must be a relationship object with a} member. The value of this key indicates new The resource will have a link. data

Client generated ID

The server can accept the ID generated by the client and the request to create resources. You must specify ID ID with a key, and its value must be a universal unique identifier. The client should use RFC 4122 [ RFC4122 ] correctly generated and formatted UUID as described in.

Note: in some use cases, such as importing data from other sources, something other than UUID may be used, but it is still guaranteed to be globally unique. Do not use anything other than UUID unless you are 100% sure that the policy you use does generate a globally unique identifier.

For example:

The server must return 403 Forbidden in response to an unsupported request to create a resource with a client generated ID.

respond

201 created

If the POST request does not contain Client generated ID If the requested resource has been successfully created, the server must return 201 Created status code.

The response should contain a Location header that identifies the Location of the newly created resource.

The response must also contain a document that contains the primary resource created.

If the response returns Resource object If it contains a self key in its member and a header is provided, the value of the {member must match the value of the header. linksLocationselfLocation

202 accepted

If the request to create a resource has been accepted and processed, but the processing has not been completed when the server responds, the server must return 202 Accepted status code.

204 no content

If the request does contain POST Client generated ID If the requested resource has been successfully created, the server must return 201 Created status code and response document (as described above) or 204 No Content status code without response document.

Note: if a response is received, the client should think that the resource object sent in the request is accepted by the server, as if the server returned it in response 204. two hundred and one

403 prohibition

The server can return 403 Forbidden in response to an unsupported request to create a resource.

404 Not Found

When processing a request that references a related resource that does not exist, the server must return. 404 Not Found

409 conflict

When processing a request to create a resource with an existing client generated ID, the server must return. 409 ConflictPOST

When processing Resource object The server must return a request that is not in the type that makes up the collection represented by the endpoint. 409 ConflictPOSTtype

The server should contain error details and provide sufficient information to identify the source of the conflict.

Other responses

The server can respond with other HTTP status codes.

The server can contain a message with an error response Error details.

The server must prepare a response and the client must HTTP semantics.

Update resources

Resources can be updated by sending a PATCH request to the URL representing the resource.

The URL of the resource can be obtained in the link of the self resource object. Or, when a GET request returns a single Resource object As the primary data, it can be updated with the same request URL.

The PATCH request must contain a resource object As the main data. Resource object Must contain type and id members.

For example:

Update the properties of the resource

Of any or all resources Attribute all It can be included in the resource object included in the PATCH request.

If the request does not include all of the resources attribute , the server {must explain the missing attribute , as if they were contained in their current values. The server must not interpret missing properties as null} values.

For example, the following PATCH request is interpreted as a request to update only the title and text attributes of the article:

Relationship update resources

Of any or all resources Relationship all It can be included in the resource object included in the PATCH request.

If the request does not include all of the resources relationship , the server {must explain the missing relationship , as if they were contained in their current values. It must never interpret them as null or empty values.

If relationships provides a relationship PATCH in the member of the resource object in the request, its value must be a relationship object with a data member. The value of the relationship is replaced with the value specified in this member.

For example, the following PATCH request will update the relationship of an author article:

Similarly, the following PATCH requests a complete replacement of the tags article:

The server can reject attempts to completely replace one to many relationships. In this case, the server must reject the entire update and return a 403 Forbidden response.

Note: since complete replacement can be a very dangerous operation, the server may choose to prohibit it. For example, if the server does not provide the client with a complete list of related objects and does not want to allow the deletion of records not seen by the client, the server may refuse a complete replacement.

respond

202 accepted

If the update request has been accepted for processing, but the processing has not been completed when the server responds, the server must {return the 202 Accepted status code.

200 good

If the server accepts the update but also changes the resource in a way other than that specified in the request (for example, updating the updated at # property or the calculated sha), it must return a 200 OK response. The response document must contain a representation of the update resource, just as GET makes a request for the request URL.

If the update is successful, the server must return a 200 OK status code, the current field of the client remains up-to-date, and the server only responds to the top level element data In this case, the server must not contain a representation of the update resource.

204 no content

If the update is successful and the server does not update any fields other than the provided fields, the server must return a 200 OK status code and a response document (as described above) or a 204 No Content no response document status code.

403 prohibition

The server must return 403 Forbidden in response to an unsupported request to update a resource or relationship.

404 Not Found

When processing a request to modify a resource that does not exist, the server must return. 404 Not Found

When processing a request that references a related resource that does not exist, the server must return. 404 Not Found

409 conflict

If the update will violate other server mandatory constraints (such as the uniqueness constraint on attributes other than), the server may 409 Conflict return when processing the request to update the resource. PATCHid

When processing a request where the resource object does not match the server endpoint, the server must return. 409 ConflictPATCHtypeid

The server should contain error details and provide sufficient information to identify the source of the conflict.

Other responses

The server can respond with other HTTP status codes.

The server can contain a message with an error response Error details.

The server must prepare a response and the client must HTTP semantics.

Update relationship

Although relationships can be modified with resources (as described above), the JSON:API also supports Relationship link Update the relationship independently at the URL of.

Note: update relationships without exposing underlying server semantics, such as foreign keys. In addition, relationships can be updated without affecting related resources. For example, if an article has many authors, you can delete one of the authors from the article without deleting the person itself. Similarly, if an article has many tags, you can add or remove tags. In the first instance, the server can use the same foreign key to implement these two protocols.

Note: if you delete a relationship (as a garbage collection measure), the server may choose to delete the underlying resources.

Update one-to-one relationship

The server must respond to PATCH from one to one Relationship link The request to the URL is as follows.

The PATCH request must contain a top-level member named data, which contains one of the following:

• Corresponding to new related resources Resource identifier object.
• null, delete the relationship.

For example, the following request updates the author of the article:

The following request cleared the author of the same article:

If the relationship update is successful, the server must return a successful response.

Update many to many relationships

The server must respond to PATCH, POST, and DELETE from one to many Relationship link URL request, as described below.

For all request types, the body must contain a data member whose value is an empty array or Resource identifier object Array.

If the client PATCH is from one to many Relationship link To make a request to the URL, the server must either completely replace each member in the relationship, return the appropriate error response if some resources cannot be found or accessed, or 403 Forbidden ， return the response if completed. The server does not allow replacement.

For example, the following request replaces each label of an article:

The following request clears each label of the article:

If the client from Relationship link POST makes a request to the URL, and the server must add the specified members to the relationship unless they already exist. If a given is already in a relationship, the server cannot add it again. typeid

Note: this matches the semantics of a database that uses foreign keys for many to many relationships. Document based storage should check the has many relationship before appending to avoid duplication.

If all specified resources can be added to or already exist in the relationship, the server must return a successful response.

Note: if the state of the server matches the state of the request, this method ensures that the request is successful and helps avoid meaningless race conditions caused by multiple clients making the same changes to the relationship.

In the following example, the comment 123 with ID is added to the comment list of the article with ID 1:

If the client from Relationship link DELETE sends a request to the URL, and the server must DELETE the specified member from the relationship or return a response. If all specified resources can be deleted from the relationship or have been lost from the relationship, the server must return a successful response. 403 Forbidden

Note: as described above for POST facing requests, this approach helps avoid meaningless race conditions for multiple clients to make the same changes.

Relationship members are specified in the same way as in POST requests.

In the following example, comments with ID 12 and are deleted from the comment list of the article with ID: 131

Note: RFC 7231 specifies that a DELETE request can contain a body, but the server can reject the request. The specification defines the semantics of the server, and we are defining its semantics for the JSON:API.

respond

202 accepted

If the relationship update request has been accepted for processing, but the processing has not been completed when the server responds, the server must return 202 Accepted status code.

204 no content

If the update is successful and the resource representation in the request matches the result, the server must return a status code. 204 No Content

Note: when the relationship already exists, this is one to many for POST Relationship link The appropriate response to the request sent to the URL. When the relationship does not exist, it is also one to many for DELETE The relationship links the appropriate response to the request sent to the URL.

200 good

If the server accepts the update but also changes the target relationship in a way other than that specified in the request, it must return a 200 OK response. The response document must contain a representation of the update relationship.

If the update is successful, the server must return 200 OK status code, the current data of the client remains up-to-date, and the server only responds to the top level element data In this case, the server must not} contain a representation of the update relationship.

403 prohibition

The server must return 403 Forbidden in response to a request for an unsupported update relationship.

Other responses

The server can respond with other HTTP status codes.

The server can contain a message with an error response Error details.

The server must prepare a response and the client must HTTP semantics.

Delete resource

You can DELETE a single resource by making a request to the URL of the resource: DELETE

respond

202 accepted

If the deletion request has been accepted for processing, but the processing has not been completed when the server responds, the server must {return the 202 Accepted status code.

204 no content

If the deletion request is successful and no content is returned, the server must return a status code. 204 No Content

200 good

If the delete request is successful and the server responds only to the top level element Data, the server must return a status code. 200 OK

404 Not Found

If the delete request fails because the resource does not exist, the server should return a status code. 404 Not Found

Other responses

The server can respond with other HTTP status codes.

The server can contain a message with an error response Error details.

The server must prepare a response and the client must HTTP semantics.

Query parameters

Implementation specific query parameters must comply with Member name The same constraints also require that they contain at least one non az character (U+0061 to U+007A). It is recommended to use U+ 002D # HYPHEN-MINUS, "-", U+005F LOW LINE, "" Or uppercase letters (e.g. camelCasing).

If the server encounters a query parameter that does not follow the above naming convention, and the server does not know how to process it as a query parameter in this specification, it must return 400 Bad Request

Note: This is to preserve the ability of JSON:API to add standard query parameters without conflict with existing implementations.

error

Processing error

The server can choose to stop processing immediately when it encounters a problem, or it can continue processing and encounter multiple problems. For example, the server might process multiple attributes and then return multiple validation questions in a single response.

When the server encounters multiple problems with a single request, the most commonly applicable HTTP error code should be used in the response. For example, 400 Bad Request may apply to multiple 4xx errors or 500 Internal Server Error may apply to multiple 5xx errors.

Wrong object

The error object provides additional information about the problem encountered while performing the operation. The error object must be returned as a keyed array at the top level of the JSON:API document.

An error object may have the following members:

• id: unique identifier of the occurrence of this particular problem.
• links: a that contains the following members Linked object:
  • about: a link , the link points to more detailed information about the occurrence of this particular problem.
• Status: the HTTP status code applicable to this problem, expressed as a string value.
• Code: application specific error code, expressed as a string value.
• title: a brief, human readable summary of the problem should not change with the occurrence of the problem, except for the purpose of localization.
• detail: a human readable explanation of the occurrence of this problem. Like title, the value of this field can be localized.
• Source: an object containing a reference to the error source, optionally including any of the following members:
  • Pointer: JSON pointer to the associated entity in the request document [ RFC6901 "/ data"] [for example, for primary data objects or specific attributes of "/ data/attributes/title"].
  • Parameter: a string indicating which URI query parameter caused the error.
• meta: one Meta object , which contains non-standard meta information about the error.