Versioning of coupled RESTful APIs with HATEOAS

Question

We have a ProductsAPI to browse products available at our site which is consumed by our mobile Apps (Android & iOS). Following is the basic design:

URL: /api/products/
Response:
[
    {
        "id" : 123,
        "name" : "abc",
        "detailsUrl" : "/api/products/123"
    },
    {
        "id" : 124,
        "name" : "xyz",
        "detailsUrl" : "/api/products/124"
    }
]

Here, detailsUrl contains the API URL for ProductDetails page.

Now, we have a requirement to make some changes in the response of ProductDetails API in new versions of apps and need to version it. The URL will be changed to - /api/v2/products/{id} (we use API versioning through URL).

Since we do not want the new response in previous version of Apps, we need to create a new version of ProductsAPI also which will send new ProductDetailsAPI url in response.

The APIs are coupled this way. If we change version of any child API, parent API version also need to be changed. What is the recommended way to handle this issue? Should we change way of versioning our APIs (use headers or something)?

score 9 · Answer 1 · answered Mar 26 '18 at 02:13

This is one of the consequences of versioning in the URL segment. I would recommend not doing that. For HATEOAS, the hypermedia should only report the identity of the related resources. It's up to the client to decide which API version they want to use.

In large APIs, it's common for services to have incongruent versions. This causes a number of issues with any approach that includes an API version in the provided link.

The service advertising the link now either makes an assumption the related resource has the same resource version or has unwanted coupling to generate the correct link
The service doesn't know what API version client wants or is aligned to. A client might be using api/orders 1.0 and api/salespeople 2.0. A service cannot know this and it's the responsibility of the client. If the service bakes the version in the link, it may not be what the client wants making it nearly worthless in the context of HATEOAS

In my opinion, there is no logical difference between api/products/123 and api/v2/products/123. At the end of the day both URLs refer to a product with the identifier 123. The API version is indicating a different representation of that product, but not a different product. To that end, a HATEOAS implementation should return the links in the form of api/products/123 and let the client decide the representation by API version using a query string, header, media type, etc. The URL segment method is the only one that cannot work this way.

score 2 · Answer 2 · answered Jul 27 '17 at 09:24

2

I'd recommend either a whole new version, so parent and child both add a /v2 into their URLs, or the use of media types. The idea of Media Types is that the clients send Content-Type headers to specify what version of the response should be returned for each resources. Using this approach avoids having to re-version a whole API, but does mean version checking for every endpoint.

A good example of media types in use is the GitHub API, you might find it useful to read the docs here: https://developer.github.com/v3/media/

answered Jul 27 '17 at 09:24

Lorna Mitchell

1,819
13
22

SMH, so for any service that changes all other services must be updated and magically re-deployed all at the same time to avoid any versioning race conditions. Wow. – Peter Ritchie Jan 23 '19 at 17:53
@PeterRitchie what do you mean by that? – Muflix May 22 '21 at 21:27
1

@Muflix I mean that each service has a shared dependency. If that shared dependency changes, every service has to change. For any services that interact with each other, they must all be re-built for that new dependency and redeployed all at the same time to avoid two or more services using different versions of that dependency. – Peter Ritchie Jun 11 '21 at 15:18
@PeterRitchie Yes, if the client/service want to use a new API version, you have to redeploy the client/service. But the previous version will be still in use so you don't need to redeploy them immediately or all at once. What other solution do you prefer? – Muflix Jun 12 '21 at 07:02
@muflix If you created a new client and it's expecting /v2, how would it work until that /v2 were deployed? – Peter Ritchie Jun 15 '21 at 13:12
@PeterRitchie I am trying but I am not able to get your point. I deploy the API which is serving both versions, for the old and also for the new clients. If the client will have info about API before it is deployed, it will have to wait, otherwise it can still use the current API. – Muflix Jun 15 '21 at 18:35

Versioning of coupled RESTful APIs with HATEOAS

2 Answers2