4

I'm developing this project using Spring and hosting in AWS EC2 instances. As few new requirements coming up, I have to change my API contracts. But I don't want to break the current clients. So, I'm trying to implement some REST APIs with versioning. So that whenever I update the endpoints the consumer applications won't crash. But I'm confused on how to do the API versioning. I thought of two ways.

  1. Create a next version endpoint in the same server,(in spring using RequestMaping("/v1/api1"),RequestMaping("/v2/api1") something like this.)

  2. Other wise completely run the v2 APIs in new server instance but keep the same API endpoint footprint and use AWS APIGateway as a proxy and configure the versioning there, then route to old server and new server depending on the version number in the request.

But the first approach will lead to lot of code duplication and code management messy I believe. Because we are keeping the same functionality with variations.

In the second approach I have to keep two set of instances for bot versions if me Version increases then It's hard to manage those instances, specially, when I will have around 15 micro-service instances. And it'll not be cost effective also. Because my company is a startup , so I need to consider this fact also.

Is there any best practices regarding API versioning and managing multiple version of endpoints? I'm open for any suggestions and guidelines. If multiple server is the solution also, I'm open to reconsider the cost limitations. I need the best solution for this problem.

Ajanthan
  • 198
  • 2
  • 10
  • `As few new requirements coming up, I have to change my API contracts. But I don't want to break the current clients.` - a perfect sign that your API is just a further Web RPC API exchanging arbitrary JSON messages and wrongly calling it REST without implementing REST principles. According to ["Uncle" Bob Martin](https://www.youtube.com/watch?v=o_TH-Y78tt4) *the Web is just a delivery mechanism* and *Architecture is about intent* and RESTs intent is to decouple clients from servers and thus making both error robust and flexible to changes. – Roman Vottner Jun 14 '18 at 17:20
  • Actually the client side requires bit modified data structure in the response now because of the customer request. So we have to modify our API to match that, that's why i want a new version. To point out the versioned APIs are different APIs anyway if we consider the endpoints. that's why we planing on the versioning. – Ajanthan Jun 18 '18 at 09:59
  • 2
    In what way does your API has to change in order to return `a bit modified data structure`? Usually the representation format should be negotiatied between client and server. Client can express what representations it supports by sending `Accept` headers and the server chooses the one it is able to server (respecting the order and highest quality factor also). The client ideally would send a negotiation request for `application/vnd.some-doctype-format+json; version=2` or something similar. If you look at HTML it defines the version inside `text/html` i.e. and thus stays backwards compatible – Roman Vottner Jun 18 '18 at 11:26

1 Answers1

3

First question is why you need a new version? Has your contract change or is there some change in internal logic and if you really need to expose a new version. Next question to ask is how long you need to support the old version and how many versions you intend to have. For a mature api and you may make use of approach 2, with smaller footprint if possible. For others you would be in better situation to expose v2 via same service and work around it. Code replication is a factor but depends on what you changing. If its all about change in contract you can try to have same biz logic and make it to work with both new and old contracts.

Here are some links that you may find useful

https://www.mnot.net/blog/2012/12/04/api-evolution

Best practices for API versioning?

Anunay
  • 1,823
  • 2
  • 18
  • 25