4

I have an API being used in an app which has URIs like these :

/API_Name_1/v1/param1/param2
/API_Name_2/v1/param1
/API_Name_3/v1/param1/param2/param3
/API_Name_4/v1/param1/param2

etc.

Now only one of my API [eg. API_Name_2] need to change while others need to remain the same. Should I just upgrade this particular one or all to the next level ?

Just renaming the remaining services so that all seem to have a common version looks unnecessary to me, but if I update just the single service, it looks like a mismatch among services versions.

Any general guidelines people follow for this ?

/API_Name_1/v1/param1/param2
/API_Name_2/v2/param1
/API_Name_3/v1/param1/param2/param3
/API_Name_4/v1/param1/param2

vs

/API_Name_1/v2/param1/param2
/API_Name_2/v2/param1
/API_Name_3/v2/param1/param2/param3
/API_Name_4/v2/param1/param2
  • What is the end of support for the older APIs? Also, what's the time till you do the next update? There comes a time where you are forced to upgrade, and it is a question of whether it's better to make the changes now while you have the hood up, or later. If you have regular updates that will happen before the API end of life, you may choose to defer updating your calls to the other APIs for those later updates. – Berin Loritsch Sep 14 '17 at 12:47
  • Can you add version parameters or some kind of GUID key as the version parameter? This way you can use Dependency Injection to on various versions of the api depending on the key and keep the urls static. Are you planning on adding new urls or changing the existing ones much? – B1313 Oct 14 '17 at 19:29
1

In essence, the question is whether you version all APIs together as a whole, or every single API for itself.

My suggestion is: Do what makes the least work, for users and yourself, consuming the API and its documentation, respectively programming the service and documenting it.

As the users will never have to work with an outdated server, thus making the question of when a new (version of an) API was introduced pointless, version them completely independently.

If the users had to contend with servers offering older versions of the whole API, it would make sense to have a new version consistently used over all APIs changed or introduced in that version for that, but still follow basically the same scheme.

1

I don't really have enough information to answer your question more specifically, but there are a number of things to consider:

  • What is the end of life for the old API?
  • What is the business priority to get your update out (how urgent is it)?
  • Does the new API change how you authenticate yourself to the system?
  • Is the API designed in such a way that you can mix and match?
  • What is the impact if you leave things as they are?

I'm facing a lot of the same questions supporting an existing application that was originally built with libraries and external dependencies that are either already end of life or rapidly approaching it. As a result, we have to be smart about how we introduce change.

One thing that you can be certain of is that APIs age and go out of support. Eventually they get removed completely. I ran into that very problem working with a Twitter integration a few years ago. The question you have to ask yourself is what the urgency is for upgrading--particularly if there are breaking changes.

My personal decision process is something like this:

  • If the end of life for the old API is at least a couple release cycles out, defer unnecessary changes until I can plan accordingly.
  • If the API changes that I have to update everything, and the new features are not critical, then talk with my customer to see if they can wait until we upgrade.
  • If the API changes that I have to update everything, and the new features are critical, then I have to make the changes now.
  • If the end of life for the old API is imminent, I have to make the changes now.

Honestly, another big question is how much impact is there to upgrade? I went through a process where I attempted to upgrade a web project to NetCore. All my back-end work was easy to update and worked with the existing web app. The changes required due to the NetCore edition of ASP.Net MVC was going to cause major rewrites. As a result, that part of it had to be postponed. We may go another route completely for the front end of our application.

My point is that version upgrades are not unique to web API versions, but you do have to know when web APIs go out of service. Once they go offline your application breaks. If you have enough time, it's best to plan the updates gradually when you can absorb the changes in your normal development cycle.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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