How to design a forward compatible REST API

I am developing a REST interface that is supposed be used by different clients. Clients as well as the server are maintained by the same team and users are expected to update their clients within some reasonable time frame. Backwards compatibility is therefore not much of an issue. I am however unsure how to plan for upcoming changes.

Taggings:

Submitted by Stefan Puntigam on Wed, 12/08/2021 - 21:35

Comments

I'm not seeing a question here, maybe narrow it somehow?
 Ondrej Brichta - Mon, 12/20/2021 - 11:13 :::
1 answer

To answer this question it is important to know whether the API fully conforms to the principles of REST. A truly RESTful API uses hypermedia as the engine of application state (HATEOAS). The entire API can be used by a client that merely knows an entrypoint and the media types that are in use. Processing is guided by media types rather than the structure of the URI. Using such an architecture, the right thing to do would be to version the media types, e.g. by offering "application/vnd.someentity.v2" besides "application/vnd.someentity.v1" when breaking changes are necessary. Content Negotiation is used when a client needs a specific version.

If HATEOAS is not employed and generic media types are used, the client has to use what Roy Fielding calls out-of-band information in order to communicate which version is required. There are many ways to do that. The most popular one is to include the version number in the URI, as in "http://example.com/v1/someentity". Using query parameters or custom request headers are other means to communicate the expected version. In any case it is important to make sure that caching works, e.g. when request headers are used the Vary header should be supported.

Submitted by Stefan Puntigam on Wed, 12/08/2021 - 21:39

Taggings:

Comments

Thank you, I was mostly only familiar with the roy fielding approach. Your solution and explanation of HATEOAS helped me with understanding some key differences for versioning between RESTful APIs and standard APIs.

 Sascha Pleßberger - Mon, 12/13/2021 - 14:28 :::

I can only join the thanks of my colleague, well explained!

 Anna Lackinger - Wed, 12/15/2021 - 08:34 :::

Thank you for your solution explanation. Working with daily with REST API I still had no experience with the versioning practice and how useful it is while communicating with different clients when you apply changes such as the way that data should be delivered.

 Parinaz Momeni ... - Tue, 12/21/2021 - 23:07 :::

Helped me a lot with another assignment i am facing Right now, Thank you !

 Moritz Ruoff Holzer - Wed, 12/22/2021 - 07:43 :::

Thanks for this explanation. I already worked a lot with REST APIs and I have always used the version in URL approach but never heard about HATEOAS.

 Nino Ziegelwanger - Wed, 12/22/2021 - 10:02 :::