1

I have a public facing REST API and SDK with multiple resources being managed: /api/v1/foo and /api/v1/bar. Both are currently version 1.

I want to make some breaking changes to both endpoints including making them more consistent (headers, date formats, etc) but since I work in an Agile environment, I will be making changes to one endpoint, releasing it, and then changing the other later. (Assume that foo gets enhanced first)

How should I handle versioning the endpoints? What are the pros and cons of different options of versioning? Are there any additional options besides these?

Option 1:

Release /api/v2/foo with new changes. Leave /api/v1/foo and /api/v1/bar deployed. Consumers that want to use the new features of /api/v2/foo would send API requests for foo to /api/v2/foo while requests for bar still get sent to /api/v1/bar. Some requests are v1 while others are v2.

Eventually I release /api/v2/bar and consumers transition off of v1 entirely so all requests are v2.

Option 2:

Release /api/v2/foo with the new changes. At the same time, I also release /api/v2/bar which is just an alias for /api/v1/bar. Consumers that want the new features stop pulling in the v1 SDK and replace it v2 SDK. All requests get sent as v2.

Eventually when I complete the enhancements to the bar API, I follow the same process above and change everything to v3.

Vadim Kotov
  • 7,103
  • 8
  • 44
  • 57
masstroy
  • 862
  • 1
  • 8
  • 22

2 Answers2

2

If you have an API on api.domain.com or domain.com/api the consumers expect that every resource has the same behavior, specially when you're dealing with with request and response headers and data formating. Then if you have one behavior on api.domain.com/v1 and you are going to change it, you should upgrade all you api resources to the new behavior and change version to api.domain.com/v2.

Even though you are an agile team, I think that releasing just one resource of an API in version v2 and all the rest of API on version v1, with different formating and request/response headers would just create an unecessary confusion among your API consumers, and maybe you should hold the on until everything is updated before a public release, and if it is not an option maybe releasing it as /beta would be enough.

If you don't think it is possible to manage and release all your resources within the same version you should consider versioning the resources and not the API as a whole, for example:

  • domain.com/api/v1/someresource would become domain.com/api/someresource/v1
  • domain.com/api/v2/otherresource would become domain.com/api/otherresource/v2

This approach doesn't solve the mess, because dealing with different behavior within the same api can be complex in the long run, but at least you align the expectations of the mess with your API's consumers.

Since maintaining different versions of an API may also hinder the speed of development, I would prefer almost always to release new resources as beta until it is possible to release the new API version as a whole.

Alessandro Oliveira
  • 1,838
  • 1
  • 13
  • 23
1

I would prefer option 2. As you are versioning your API rather than only certain methods this approach seems to be more consistent from my point-of-view. As a developer, that's my opinion, I would not expect to make calls to different versions of the same API.

If I choose to switch to v2 I can determine based on the release notes that foo has changed and update my application correspondingly. Still I can call bar the same way as it hasn't changed yet and I don't have to consider that I need to call bar and everything else with API v1 and only foo via v2.

As soon as you release v3 you explicitly state that bar has changed with this new version and I will deal with the changes as well.

If you think of an app, desktop application or library you would also increase version numbers of the whole application whenever a new change has happened that shall be released. Users or developers would also use one version of the application or library version at once.

So I would treat the REST API no different and allow your users to allways being able using only one specific API version at once.

afh
  • 1,488
  • 1
  • 5
  • 8