V8-archive: Add /revisions endpoint

[rijkvanzanten]

There is currently no way of accessing the revisions from the API. The application needs this to be able to render / make available the rollback functionality

[wellingguzman]

Four endpoints:

• GET /revisions - Fetch all revisions from directus_revisions collection.
• GET /revisions/<id> - Fetch the revision with the given id from directus_revisions collection.
• GET /revisions/collection/<collection> - Fetch all revisions from a given collection.
• GET /revisions/collection/<collection>/<id> - Fetch all revisions of a given item id and collection.

[rijkvanzanten]

@benhaynes Add to reference please 😄?

[benhaynes]

Sure! But first, do we want /items/[collection-name]/[pk]/revisions (or something like that)? Worth an alias? Seems more natural, like: I'm looking for an item... now I'm looking for a different revision of that item.

Thoughts? @WellingGuzman @rijkvanzanten

[wellingguzman]

I believe /revisions/collection/<collection>/<id>, instead of using /items/[collection-name]/[pk]/revisions, as it wraps everything on revisions.

But I also like having it on items because of this: /items/[collection-name]/[pk]/revisions/<revision> which makes more sense to use alongside with /items/[collection-name]/[pk]/revisions

[benhaynes]

Exactly.

I think we could make the item revision endpoint more useful... using an 0-based offset instead of the revision id. Like this:

Syntax:
/items/[collection-name]/[pk]/revisions/<revision-offset>

Example2:

• /items/projects/1/revisions (fetches all revisions for this item)
• /items/projects/1/revisions/2 (fetches SECOND FROM CREATION revision from this item)
• /items/projects/1/revisions/-2 (fetches SECOND BACK FROM CURRENT revision from this item)

[rijkvanzanten]

All in favor of this? Aye

[benhaynes]

Aye!

I think we keep the current ones in system (using revision.id)... but add the /items revisions with the offset too.

[wellingguzman]

Are we getting rid of All /revisions endpoints or are we going to add items revisions as extra for fetching revision offset?

[benhaynes]

Add extra...

[wellingguzman]

Final endpoints?

• GET /revisions - Fetch all revisions from directus_revisions collection.
• GET /revisions/<id> - Fetch the revision with the given id from directus_revisions collection.
• ~GET /revisions/collection/<collection> - Fetch all revisions from a given collection.~
• ~GET /revisions/collection/<collection>/<id> - Fetch all revisions of a given item id and collection.~
• GET /items/<collection>/revisions - Fetch all revisions from a given collection.
• GET /items/<collection>/<id>/revisions - Fetch all revisions from an item.
• GET /items/<collection>/<id>/revisions/<offset> - Fetch the revision at <offset>.

[benhaynes]

I updated your comment to keep this clean... that should be accurate. @rijkvanzanten ??

[benhaynes]

Hmm, would this mean we also need to reserve revisions as a primary key string? If so, maybe we move THAT endpoint back to the System one at /revisions.

GET /items/<collection>/revisions

[benhaynes]

Lastly, do we want to combine /revisions/[collection-name] and /revisions and use filters param instead? That would make it more like the other endpoints.

[wellingguzman]

Hmm, would this mean we also need to reserve revisions as a primary key string? If so, maybe we move THAT endpoint back to the System one at /revisions.

What do you mean? directus_revisions will be a integer primary key, why would we need to change it string?

Lastly, do we want to combine /revisions/[collection-name] and /revisions and use filters param instead? That would make it more like the other endpoints.

Agreed! that's why I believe we should remove the /revisions/[collection-name] and /revisions/[collection-name]/[revision-id] endpoints.

[benhaynes]

No no, if I have a projects table where the primary key is a string... and one of my pk is revisions... that would break this endpoint:

GET /items/<collection>/revisions
GET /items/<collection>/revisions/revisions

[wellingguzman]

Oh! True! I prefer moving back to the system endpoint, where we know we have integer as primary key.

@rijkvanzanten?

[wellingguzman]

oh wait, what about getting rid of GET /items/<collection>/revisions and just use GET /revisions?filter=<filter collection>?

[benhaynes]

I agree!

This seems like the final endpoints:

• GET /revisions - Fetch all revisions. Can use filter param to get only one collection
• GET /revisions/<id> - Fetch the revision with the given id from directus_revisions collection
• GET /items/<collection>/<id>/revisions - Fetch all revisions from an item
• GET /items/<collection>/<id>/revisions/<offset> - Fetch the revision at <offset>

[benhaynes]

Awesome. If it helps, I've already tried to update the new API Docs with these endpoints 😀

[wellingguzman]

So it's official! I'm going to update the endpoints.