http://jsonapi.org/format/#crud
Problem/Motivation
While working on
#2931785: The path for JSON API to core →
, I think we overlooked one very important thing wrt spec compliance. The fact that the JSON API module for Drupal incorporates two spec extensions:
- Fancy filters: https://gist.github.com/e0ipso/efcc4e96ca2aed58e32948e4f70c2460
- Partial success: https://gist.github.com/e0ipso/732712c3e573a6af1d83b25b9f0269c8
… yet we support Accept: application/vnd.api+json and Content-Type: application/vnd.api+json. Which signifies we're implementing the base spec. Additionally, we're not even mentioning in jsonapi.api.php that this module implements more than just the base spec!
http://jsonapi.org/format/#content-negotiation says:
Content Negotiation
Client Responsibilities
Clients MUST send all JSON API data in request documents with the header
Content-Type: application/vnd.api+json without any media type parameters.
Clients that include the JSON API media type in their Accept header MUST
specify the media type there at least once without any media type parameters.
Clients MUST ignore any parameters for the application/vnd.api+json
media type received in the Content-Type header of response documents.
Server Responsibilities
Servers MUST send all JSON API data in response documents with the header
Content-Type: application/vnd.api+json without any media type parameters.
Servers MUST respond with a 415 Unsupported Media Type status code if
a request specifies the header Content-Type: application/vnd.api+json
with any media type parameters.
Servers MUST respond with a 406 Not Acceptable status code if a
request’s Accept header contains the JSON API media type and all instances
of that media type are modified with media type parameters.
Note: The content negotiation requirements exist to allow future versions
of this specification to use media type parameters for extension negotiation
and versioning.
… and sadly, JSON API's extension system was reverted. http://jsonapi.org/extensions/ currently says … on May 21, 2015.
In https://github.com/json-api/json-api/issues/614, Roy Fielding (of REST fame) is quoted to have written that media type negotiation like vnd.api+json is meaningless. He clarified his statement at https://github.com/json-api/json-api/issues/614#issuecomment-101741478. That issue spawned https://github.com/json-api/json-api/pull/650, which tried to improve things, but it was considered "too late before the imminent 1.0 release". Then, ironically, it is https://github.com/json-api/json-api/pull/660, which is mentioned nor linked in neither of the two issues above (614 an 650), and it simply removed the concept of/support for extensibility altogether. This was May 21, 2015.
It was worked on a bit in November 2015, in https://github.com/json-api/json-api/issues/915. Again in December 2015, in https://github.com/json-api/json-api/pull/957. And then again in https://github.com/json-api/json-api/pull/1195, in July 2017. And finally, https://github.com/json-api/json-api/issues/1207 in August 2017.
https://github.com/json-api/json-api/issues/1207 is the latest and greatest, confirmed by spec author dgeb at https://github.com/orbitjs/orbit/issues/479#issuecomment-358654119 on Jan 18, 2018. but it still hasn't actually gone anywhere — there's still nothing spec implementers can actually do …
Finally, note that http://jsonapi.org/format/#content-negotiation (quoted in full above) says the server must send an error response if any media type parameters are specified!
Proposed resolution
- Update
jsonapi.api.php to state that the JSON API module implements the base spec + 2 extensions
- Figure out how to communicate in our HTTP responses that it's the base spec + 2 extensions … even though the JSON API spec literally forbids it, and there's a whole string of GitHub issues: 614, 650, 660, 915, 957, 1207.
Remaining tasks
Discuss!
User interface changes
TBD
API changes
TBD
Data model changes
TBD