4

We are developing internal api's for integrating the server side logic (backend) with frontend (web, mobile etc). We have a java stack in our backend and front end is coded in react and react native. Since both of these are developed by our organization, as API providers we have complete control over the API consumers. Any change in the api could be synced up with the change in the api clients.

Are there any scenarios/use cases where we need to think of versioning internal/private api's? Do we need to think of a versioning strategy?

Improve this question
4
  • 6
    Thought experiment: what happens if not all of the clients are on the latest version and you make a change to the API without versioning it?
    – Robert Harvey
    Commented Mar 8, 2018 at 5:08
  • 5
    The end-user might or might not update the mobile app. They usually do it, but there's no guarantee.
    – Laiv
    Commented Mar 8, 2018 at 6:08
  • 3
    You also have to be always aware of the backward compatibility between device generation and the SDK you used to build and compile the apps. Sometimes, the user can not update the app due to old versions of the OS. For instance, if tomorrow StackExchange decide to make this app only compatible with Android 7, I'm so fu...d, since my mobile is stuck in Android 6.
    – Laiv
    Commented Mar 8, 2018 at 7:11
  • 4
    Even if you'd leave mobile out of the equation, deployment of both a backend and a website would have to happen at the same time if you don't have versioning for your API. I'd say having a versioning strategy worked out is worth the effort even for that scenario. Adding mobile in the mix makes versioning of the API a must have.
    – Jonathan van de Veen
    Commented Mar 8, 2018 at 8:48

2 Answers 2

Reset to default
4

You should have a versioning strategy because that is key to independent evolvability, but it should be tied to Content-Type, not URLs or anything else.

Even in a closed-house setting, you should still strive to make all components of a system independently evolvable (isolated, modularised) — especially a distributed system like a client/server-based one. This both allows different teams to work on each at their own pace, and allows for different release cadences.

Why not in URLs?

URIs identify abstract things which cannot be versioned, like a user "Andy", or an invoice. A representation of that thing will have a particular serialisation, which can be versioned, application/andys-api-v1+json.

Your API (as with any website) is defined by three things. These are the only things that you need to document if your API is RESTful:

  • The root URL
  • The content type(s) of representations
  • the link relations between URIs

If a v1 client obtains a link to /users/andy from a previous request, it can forward that to a v2 client, which can then make a request to the same URL to get data about the same Thing, but in a language (content-type) it can speak, application/andys-api-v2+json.

The v1 and v2 clients might be different parts of the same program, in the midst of a development cycle. The key is that the clients both continue working throughout.

Improve this answer
4
  • Why put the version into the content type? other versions often also come if different semantics and business logic. Why not put the version into a separate header and leave the content type to be application/json (or whatever format you happen to use)
    – marstato
    Commented Apr 8, 2018 at 17:28
  • @marstato Putting the version into a header, rather than e.g. the URL, allows clients to negotiate for it using Accept & Vary semantics that are already well understood and deployed by middleware like caching proxies, but still share an identifier, the URL, between v1 and v2 clients. And specifically using the Content-Type header is ideal as different formats (v1 and v2) have different binary representations, just as JPEG and PNG versions of an image have different binary representations but reflect the same resource (in the HTTP sense of the word "resource").
    – Nicholas Shanks
    Commented Apr 10, 2018 at 14:25
  • @marstato Whilst you could negotiate on a custom header, and that would be still better than encoding versions into a URL, you would lose the semantics that Content-Type already possesses, namely that the thing that is different is the binary representation, and to be able to understand the document (rather than just parse it) you need to speak "application/vnd.my-doc-v2+json" rather than just "text/json". You would also have to make up a new header and clients would have to add additional code for that.
    – Nicholas Shanks
    Commented Apr 10, 2018 at 14:31
  • This is good in theory. For DX, versioning in URL is 1000x easier to work with.
    – Pithikos
    Commented May 23, 2023 at 11:21
0

Create a text file called 'resource.html' on your file system when you want that version of the file you 'get' it by name. Copy the file, change its contents and rename it 'resource1.html'. now you can get both versions by name. REST is supposed to be a mechanism by which we leverage existing HTTP protocols.. so how do you version a REST resource? By name (URL). Get /server/version/resource. You can put the version anywhere you like in the URL.. as long as EACH UNIQUE resource has a unique URL.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.