Support content revisioning

I think that this is a good candidate for a sub-module or a separate contrib. There are many ways to do revisions (think of workspaces, or time based revisions, etc.). There are also competing formats to express those.

I don't think the JSON API module needs to be opinionated about these. However I would think that a module could use many of the JSON API tools to achieve this goal.

I think that this is a good candidate for a sub-module or a separate contrib. ... However I would think that a module could use many of the JSON API tools to achieve this goal.

I'm curious how this might work in another module, @e0ipso, it sounds like you already have some thoughts about that?

There are many ways to do revisions (think of workspaces, or time based revisions, etc.). There are also competing formats to express those.

Perhaps there is some infrastructure we could provide to establish a baseline of functionality?

For example, no matter the way revisions are done, revisions always have a "previous" version, pretty much by definition. The same is almost always true for a "canonical" or "default" version.

No matter what, there ought to be a way to express a URL for those revisions.

I like @Snugug's suggestion of: http://example.com/jsonapi/node/article/{uuid}?version={vid}, but I would slightly amend version={vid} to version={we_dont_care}, so that we aren't tied to a version identifier and so it would permit a revision provider to have aliases like version=latest

It seems to me that any complementary module would need a way to:

1. Influence the loaded entity on an individual basis. I.e. cause JSON API to load a different revision than the default.
2. Express the revision state. I.e. to answer the question "is this the canonical version?" "is this an editable revision?"
3. Express how a particular revision relates to another revision.

Concretely, I think we need to decide on a URI template for addressing a particular revision and use that template to load particular revisions. I think we also need to figure out HATEOAS links such that a module can provide links to a prior, canonical, editable version etc.

Relying on RFC5829 seems like the best approach, particularly the idea that navigation between versions should be based on link relations, not JSON API relationships.

Unknowns
Collections/filtering and includes seem to be the biggest unknowns here. I'd like to propose that we simply punt on them and do only what we can without solving every possible problem.

Collections are difficult because there's no way in the entity query system to query particular revisions. One is limited to the blunt: currentRevision(), latestRevision() or allRevisions() methods.

Includes are difficult because if you attempt to include an entity while viewing a particular revision, which version of the included resource should we include?

In both cases though, I think we can #donothing to start. We don't need to support include query params in conjunction with revisions and we don't need to support the version query param on collection routes. This could be added over time as patterns emerge from initial individual GET support and as Drupal core support gets better.

This issue is a duplicate of #2795279: [PP-2] [META] Revisions support. Also semi-related: #2832164: JSON API: forward compatibility with Workspace module.

#2946972: EntityResource: revisions support is the sister issue for core's rest.module.

This would be an extension to the JSON API spec. And JSON API 1.0 does not have an extension mechanism yet, that's being discussed in https://github.com/json-api/json-api/issues/1207, and we (Drupal community/JSON API Drupal module maintainers) are participating in it. That upstream issue is blocking #2955020: Spec Compliance: JSON API's profile/extention (Fancy Filters, Drupal sorting, Drupal pagination, relationship arity) needs to be explicitly communicated.

Relevant JSON API issues for this issue: https://github.com/json-api/json-api/issues/749 + https://github.com/json-api/json-api/issues/41.

As much as I applaud opening an issue for this, I do think it'd be better to close this and move all of its comments into #2795279: [PP-2] [META] Revisions support. It's impossible to keep track of all discussions about the exact same subject/scope otherwise.

Everyone +1 to that?

Everyone +1 to that?

+1

I'll respond to your other points over there.

Thanks for the report @Snugug. I'll link this issue in #2795279: [PP-2] [META] Revisions support.