From the course: Building and Securing RESTful APIs in ASP.NET Core

Approaches to API versioning - ASP.NET Core Tutorial

From the course: Building and Securing RESTful APIs in ASP.NET Core

Start my 1-month free trial

Approaches to API versioning

“

- [Narrator] No matter how much planning and design you put into your API chances are good that sometime down the road you'll need to make some changes. Some modifications like adding new routes or properties shouldn't cause any problems at all. However if you need to make breaking changes that could affect existing clients out in the wild you'll need to think about a strategy for versioning your API. How to properly version a RESTful API is a hot topic of debate. Let's take a look at some of the options. The most RESTful way of versioning an API is to not version it at all. Hypertext does the engine of application state means that clients shouldn't hard code any assumptions about how the API behaves. In other words clients should be dynamic and only rely on the API responses. If your clients are truly dynamic like web browsers are, even breaking changes to the data or structure of the API responses shouldn't affect them. That being said you might still need to make breaking changes to the API that even dynamic clients won't be able to keep up with. If this is the case, you can fall back to versioning the API using the content negotiation process that already exists in HTTP. When clients request a media type using the Accept header they can explicitly include a version number or string in the media type itself. For example a client could request the /rooms route and specify that the client accepts the application/ion+json;v=2.0. Your application can read this header and return API version 2.0 of the rooms route if it exists. The downside of versioning using the media type is that it's not always immediately obvious to clients that they can request a different version in this way. The third option is to directly include the API version in the URL. In my opinion this is the least RESTful way to version the API because it means the URL is no longer an opaque unique identifier. If the client saves specific references or bookmarks to resources by URL and later the URLs change those references will break. It also means that incrementing the API version means branching the entire API whereas versioning with the media type gives you more flexibility to version specific routes. One advantage URL versioning does have over media type versioning is that it's much more explicit because clients can directly see the version in the URL. Many developers are more familiar with this style of versioning since it's used on a lot of popular APIs. Which approach you should use depends on your project and your goals. Do you want versioning that's more explicit to clients and developers or more flexible and clean? Are you expecting the interface to be stable or have breaking changes often? Planning and thinking through all the use cases of your API in advance can reduce the need to make breaking changes down the road. For the land and hotels API, I'll go with the media type versioning approach. I'm not anticipating having to make breaking changes often to the API but we'll add versioning support early on just in case.

Contents