Learn the approaches to RESTful versioning and how they differ. Nate explains media type and URL versioning, discusses the pros and cons, and determines 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.
- REST vs. RPC
- Using HTTP methods (aka verbs)
- Returning JSON
- Creating a new API project
- Building a root controller
- Routing to controllers with templates
- Requiring HTTPS for security
- Creating resources and data models
- Returning data and resources from a controller
- Representing links (HREFs)
- Representing collections
- Sorting and searching collections
- Creating forms
- Caching and compression
- Authentication and authorization for RESTful APIs
Skill Level Intermediate
Building Web APIs with ASP.NET Corewith Chris Woodruff1h 7m Intermediate
Deploying ASP.NET Core Applicationswith Nate Barbettini57m 57s Intermediate
1. REST API Concepts
2. Building a Basic API
3. Securing the API
4. Representing Resources
5. Representing Links
6. Representing Collections
7. Sorting Collections
8. Searching Collections
9. Forms and Modifying Data
10. Caching and Compression
11. 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.