Learn the approaches to RESTful versioning and how they differ. Discover media type and URL versioning, the pros and cons, and which style the sample project will use.
- [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.
- What is RESTful design?
- Building a new API with ASP.NET Core
- Using HTTP methods
- Returning JSON
- Creating RESTful routing with templates
- Securing RESTful APIs with HTTPS
- Representing resources
- Representing links
- Representing collections
- Sorting and searching collections
- Building forms
- Adding caching to an ASP.NET Core API
- Configuring user authentication and authorization
Skill Level Advanced
1. REST API Concepts
2. Build a Basic API
3. Versioning and Errors
4. Secure the API
5. Represent Resources
6. Represent Links
7. Represent Collections
Add pagination7m 37s
8. Sorting Collections
9. Searching Collections
10. Forms and Modifying Data
11. Caching and Compression
12. Authentication and Authorization
- Mark as unwatched
- Mark all as unwatched
Are you sure you want to mark all the videos in this course as unwatched?
This will not affect your course history, your reports, or your certificates of completion for this course.Cancel
Take notes with your new membership!
Type in the entry box, then click Enter to save your note.
1:30Press on any video thumbnail to jump immediately to the timecode shown.
Notes are saved with you account but can also be exported as plain text, MS Word, PDF, Google Doc, or Evernote.