murrekatt murrekatt - 23 days ago 5
reST (reStructuredText) Question

Replace immutable resource in REST API

I have a REST API which allows creation and update of some resource, let's say cars.

POST /cars
POST /cars/:id

A car has among others an
field which is generated on creation by the server.

I would like to allow some business processes that use these cars to see each "revision" of a car as immutable but allow changes to the cars over the REST API so that a new "revision" is created. These revisions are on a timeline and depending on when a change is made a business process will either use it or not.

I would like to hear some thoughts on this and how to go about it.

A somewhat hacky solution is of course to just keep the cars immutable and the ID is the "revision" handle so to say. An update results in a new car with a different ID. Of course somewhat strange to call an API with an ID and get back another ID.

Thoughts and suggestions? Thanks!


OK, after looking at the suggestion to look into revisions and how StackExchange uses those for revisions across questions and answers I wonder how to practically deal with
in terms of which object has which fields and how to find e.g. the latest version of a specific car identified by

For instance, a car has:

id: 1
brand: Toyota
model: Yaris
price: 1000

Let's say the price can change over time and this should be captured by a revision of the car, e.g.:

car_id: 1
revision: 1
price: 900

Let's say I would like to get the latest car with ID 1 and it should give me that Toyota Yaris that now costs 900 instead of 1000. Are those the expected values now in the database, i.e. two rows and the latest revision (if found) overrides the other? How does this work?


OK, so the revisions is just to keep track of the history and the latest information is in the
entry itself. I.e. when an update occurs, a new revision is created with the previous values in addition to updating the cars entry. Both done in a transaction.

Answer Source

Why don't you handle it in a similar way as the Stack Exchange API?

GET /posts/{ids}/revisions

There's also an endpoint just for retrieving revisions:

GET /revisions/{ids}


Besides a static mapping such as /revisions/1 or /revisions/2, your API could provide a URI that points to the current/latest revision, such as /revisions/current or /revisions/latest.

A resource can have a mapping whose value changes over time and it's the case of the identifier for the current/latest revision.