Building APIs can be a difficult and daunting task for many web developers. With ASP.NET Web API, building APIs has been simplified. In this course, you are going to build a new API using Web API by adding it to an existing ASP.NET Project.
Building APIs can be a challenge for many web developers but with ASP.NET Web API, this process can be simplified. In this course, Building an API with ASP.NET Web API, you will learn foundational knowledge and gain the ability to implement and build your own API's. First, you will learn and understand the role of Functional APIs in larger systems. Next, you will discover how to build association APIs to make obvious, self-documenting APIs. Finally, you will explore how to implement a complete API using Web API. By the end of this course, you’ll know how to implement a complete, maintainable API using ASP.NET Web API.
Shawn Wildermuth has been tinkering with computers and software since he
got a Vic-20 back in the early '80s. As a Microsoft MVP since 2002, he's
also involved with Microsoft as an ASP.NET Insider and
Course Overview Hi everyone, my name is Shawn Wildermuth, and welcome to my course, Building an API with ASP.NET Core. I'm a Microsoft MVP, instructor, and developer. The skill of building a web-facing API isn't optional anymore. Whether you're building a website, a mobile app, a SPA, or an enterprise tool, building a well-designed API is required. In this course, I'm going to introduce you to REST. We're going to design and build an API from start to finish and show you how to version your API too. Some of the major topics we'll cover include, use ASP.NET Core to build reliable APIs, understand REST and when to be pragmatic about it, how to use models and validation, and how to version your APIs. By the end of this course, you'll know how to implement an API that's easy to use and easy to maintain. Before beginning with this course, you should be familiar with ASP.NET Core and Entity Framework Core. I hope you'll join me on this journey to learn to create an API with ASP.NET Core with my Building an API with ASP.NET Core course, here at Pluralsight.
Pragmatic REST Welcome to Building an API with ASP.NET Web API. My name is Shawn Wildermuth. In this first module, we'll talk about pragmatic REST. So the purpose of the course is to help you build a web API. You're going to learn by doing, and you can just follow along, as I'm going to write all the code from the project we're going to start with, all the way to a completed API. There'll be no magic of dropping in a bunch of code that we have to explain. You'll actually see me build it all. The course is meant to teach you how to build an API specifically with ASP.NET Web API. I'll show you how to create your own controllers, how to query and modify data, how to use association controllers, how to define operational APIs, and finally, how to version your APIs. As of the recording of this course, we're going to be using Visual Studio 2017. Specifically, I'm using 15.9, which is a very late version of it. This should work in other versions, but there's no guarantees. I would say you need at least 2017 to follow along with this course. We'll be using .NET Framework 4.7 .2, Web API 2, and Entity Framework 6. If you don't have any of these, you can get them all at get.asp .net, and it's fine that you'll use Visual Studio Community edition. You do not need to have a paid version of Visual Studio to follow this course. If you have questions during the course, feel free to go to the Discussion tab of this course, and I'll be answering questions and helping you get unstuck if you're confused.
Your First API In this next module, we're going to be building our first API. So in Web API, the way that a request turns into a response is pretty straightforward. A request comes in, let's say there's a GET for api/customer, and the api/customer represents a route, or a match of the URL. That route searches through all the routes that are inside of the system for a specific match. It's trying to find that string that is api/customer and find a route that can serve it. From there, it matches it to an action on a controller, it executes the action, and then the result from the action gets returned as the response. So we're going to take that whole story, and we're going to look at it in code. Let's do that next.
Modify Data Welcome to the next module on modifying data. Let's start and think about how our URI has been designed. If we're going to look at something like a list of customers, we want to think about the URI design not just in the characters in the URI, but what should we expect from them when we have any of the verbs? So in a GET, we should expect a list of customers, like we did in the last module. But in a POST, we should assume that we're going to create a single new customer. A PUT will update a batch of customers, and DELETE will return an error. There may be occasions where you want to support deleting an entire resource, but I think that's pretty rare. When you're looking at the URI for an individual item inside the resource, you can expect that the GET is going to get that individual item, again, like we did in the last module, that a POST will return an error. And the reason that it's going to return an error is that you can't create an item that already exists. A PUT will update that individual item, and then the DELETE will delete that regular item. And for just /customers, that GET that's going to return the collection will be that list of items, the POST against customers will return the new item, a PUT will return the status code only in that it's going to show you whether the update to the collection of customers succeeded or not, and then the DELETE will return just a status code as well, which of course will be an error status code. When looking at the URI for an item again, issuing a GET will return the item, issuing a POST will return the status code, but again, only an error code, the PUT will return the updated item, as well as success, and then the DELETE will just return a status code, usually of success, as you want to delete an individual item. Returning the item you just deleted makes little sense. Now that we have a sense of how POST, PUT, and DELETE are going to act in these situations, let's go ahead and write that code.
Associations in APIs Next, we're going to talk about Association APIs. When designing your API, you often have resources that are related to each other, and we can model them in the API as associations. For example, we've been using api/camps to give us access to the camps resources. We've also used a single identifier to be able to get at an individual camp resource. But these camps can have talks and speakers, so we can use the URL to segment the talks for a particular camp without creating another top-level API, but this is what we would talk about as an association API. We'd follow the same pattern of creating another segment to the URI to represent individual talk IDs. As we implement the parts of the API like we've done in the last couple of modules, we're going to implement the collection of camps and the individual camps in a CampsController. When we're creating associations, we can create a separate controller that is responsible for those associated resources. Let's go ahead and implement this TalksController so you can see what that means.
Functional APIs Next, we're going to talk about creating functional APIs. As we've talked about before, we're really trying to hone in on creating APIs using pragmatic REST. A chief piece of what we've looked at so far is using URI endpoints and resource URIs to specify things that you want to interact with on the server, specific resources. The problem with that is there's some times that you need to be able to build functional APIs. So REST itself defines URIs as resources on the server, but eventually, you're going to run into exceptions. You're going to need something on the server that's just going to do some functional operation. This operation may be starting a print job, it may be clearing cache, or kicking off some other operation. So don't be afraid of using functional APIs when they are the exception. The problem with functional APIs, once you go down that road once, you do start to think about the API as Being remote procedure call based instead of really API based. So while we're going to talk about how to create to these functional APIs, they should represent a really small part of your API. So at what point would you want to use functional APIs? They're typically used for operational needs, not for data needs. Don't use functional APIs for building reports. There are better ways to do that, and because it's still data based, you're going to want to go through the RESTful APIs instead. One rule of thumb is that if you're returning data, you're not building a functional API. Let's go ahead and build a simple functional API so you can see what I mean.
Versioning Your API And finally, we're going to talk about versioning your API in this module. So when I talk about API versioning, what exactly do I mean? Regardless of whether your API's meant for internal users or external users, once you publish that API, it's set in stone. People will be writing code against it. That means that your users or customers, they're going to rely on that API not changing and breaking their code. But as requirements change for different customers, you're going to want to be able to make those changes. You need to have a way to change the API without breaking that old code. First rule here is to not break old clients. But don't get API versioning confused with product versioning. If you tie them strictly together, it means you can only change API versions in very small ways. So API versioning can be troublesome, and because it could be, a lot of APIs are written without versioning in mind. When we do typical .NET versioning, we do this with package versions, whether that's using something like NuGet, or it's just enforcing contracts. And these package versions are really tied to assemblies as a unit of work. But in API versioning, this is more difficult. You need to be able to support the old and new users, even though you really only have one set of endpoints. Side-by-side deployment of different versions of something like an assembly just isn't feasible. Your single code base needs to support both versions, or often multiple versions, of your API. So at this point, I've probably scared you, but let's talk about some common schemes for versioning your API. Let's do that next.