Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Introduce Profiles to v1.1 #1268
Note: Although this PR has my name attached to it, it represents a lot of hard work by @ethanresnick in particular over the past several years. Ethan, @wycats, and I have closely collaborated to reach a mutually acceptable solution in an attempt to finally push this over the finish line. This may yet be tweaked a little as some last minute adjustments have yet to be reviewed by Ethan and Yehuda. And of course we welcome feedback from the rest of the community.
Profiles are a means to describe additional semantics the JSON API media type, without altering the basic semantics. In other words, a profile describes a fully-compliant, yet more opinionated, implementation of the spec. It is hoped that profiles will unlock new layers of shared conventions.
A profile can essentially turn every MAY or SHOULD in the base spec into a MUST. Profiles might describe how the
Profiles are identified by URI, which ideally should dereference to a document that describes the semantics of the profile.
One or more profiles may be associated with the JSON API media type through the
In order to require the application of one or more profiles, the profile(s) must be specified with the
Any structural elements introduced by a profile can be aliased. This allows for better adaptability and composition of profiles. A new profile descriptor object is introduced which allows for declarations of aliases in a particular document.
First off: thanks to everyone for this epic work, in this issue and related issues!
I'm reviewing this as one of the people doing the work to bring JSON API support to Drupal core. Note that there are already >5000 Drupal 8 sites using JSON API (that usage count is an underestimation: it's the lower bound).
As mentioned in #1207, we're working to minimize/reduce risk as much as possible, by having detailed attention to API surface and its implications: backwards compatibility, maintainability, supportability. We managed to achieve zero configuration: install this module and all Drupal data is instantly exposed via JSON API, respecting the existing access control logic. If users can view
Specifically, the https://www.drupal.org/project/jsonapi module for Drupal (that we're working to move into Drupal core itself) uses two extensions: "Fancy Filters" and "Partial Success" — see https://www.drupal.org/project/jsonapi/issues/2955020. Without the former, no querying of resources (e.g. only published articles written by Wim), without the latter, impossible to do per-resource access control (e.g. Wim can see unpublished articles, but Gabe can't).
Today, and for the past ~2 years, those extensions are always running, but their existence is not communicated explicitly, because the JSON API 1.0 spec does not support extensions, per http://jsonapi.org/extensions/.
Therefore this issue/PR is essential for JSON API support to land in Drupal core. Otherwise we risk future JSON API specs moving in directions incompatible with what Drupal's JSON API implementation does … and then we would have a massive backwards compatibility problem.
I wanted to call out a two specific concerns they raised, and whether this PR addresses them:
This would mean no BC break in the current
I don't think this concern is fully addressed? I think the conflict @gabesullice explained/predicted there still exists. I can understand that his
Looking forward to your thoughts about this :)
Review of the actual PR to follow.
FYI: this is being implemented for Drupal at https://www.drupal.org/project/jsonapi/issues/2955020.
@wimleers Thanks for the review, and sorry for my delay in addressing your comments. I've been swamped.
I don't think any of your comments suggest that this PR needs serious changes, which is reassuring. The possible exception is the around the developer experience of requiring long urls in the
EDIT: I think the solution here is simple: the server can interpret each query parameter as coming from the profile of its choice by default (though it can't change that choice over time). In other words, it can implicitly interpret
Does that approach work for everyone?
I'm not sure I understand this. Can you give an example?
This was referenced
Jun 15, 2018
@ethanresnick I agree that this is the most simple and elegant solution. The critical part here is that the JSON:API resource(s) (i.e. HTTP resource) identified by a request does not change for a given URL. If usage of a profile targets different resource(s), then the same URL must not be used. And we explicitly provide the
No need to apologize — I know the feeling all too well!
I'll let @gabesullice reply to this — it's possible I'm misinterpreting what he wrote.
This means that the Drupal JSON API module — which is currently on a path to inclusion into Drupal core itself — now actually could implement this. How certain are we that there will be no more breaking changes in the spec wrt profiles?
I reopened the Drupal.org issue: https://www.drupal.org/project/jsonapi/issues/2955020#comment-12781015.
I can't forsee any changes, except if implementation experience proves that some part of this design is really unworkable.