Join Michael Sullivan for an in-depth discussion in this video Understanding REST, part of Learning ASP.NET (2014).
Before we spend some time building an ASP.net web API, let's talk a little bit about the REST architectural style, what its purpose is, some features of a REST API, and how it compares to other ways of setting up an API. REST stands for representational state transfer. The name is actually pretty self-explanatory and just refers to the passing of information, as described by representation, of some data that has a current state. And, for instance, we may just want to fetch it or request that it be updated in a certain way.
But there's a lot more to it in terms of the way that's done and some constraints that are applied. The term came out of a doctoral dissertation written by a guy named Roy Fielding, who's well known for his work on the HTTP specification in the Apache HTTP server, among other things. Instead of trying to summarize the paper, let's start by mentioning a few things that REST aims to promote. The first is stateless client-server interaction. Maintaining state, for instance a user session, can consume a lot of resources for a server.
So instead of burdening a server with a task like that, we'll try to make requests that don't depend on any information being maintained in memory on the server. Another is a uniform interface that makes use of the existing HTTP and URI standards. So in contrast to something like a SOAP message, which has its own arbitrary structure and abstractions, it might be sent to a generic service that just handles all kind of messages. We'll use our existing HTTP verbs like GET and POST and others, with a URI that identifies a specific resource that we're retrieving or updating for example.
REST also encourages layered systems. The fact that we're using basic HTTP requests in identifying individual resources, doesn't mean that our underlying system can't be more complex than that in nature. So layering is how we can make sure the interface can always conform to these standards that we're talking about, because the actual implementation can be hidden in the lower layers. And finally, because our goal is effective stateless interaction between client and server, caching becomes very important.
Caching can certainly be done at the server level, but when I say cacheability information, I mean that the server should do a good job of letting the client know what information can be cached and for how long. Roy makes a very good point in his dissertation that, the most efficient network request is one that doesn't use the network. And by that, of course, he means that the response can be retrieved from the cache, freeing up bandwidth and resources. When we build an API using the guiding principles of REST, we say that it's a RESTful API, or a RESTful service.
So were going to use GET and POST appropriately for fetching and creating resources, and we'll use, among other HTTP verbs, PUT for replacing resources with entirely new ones and in effect updating them and DELETE for deleting resources. The idea with that one, for example, is that we already have a DELETE HTTP verb, so why not use it to make the request more meaningful? We'll also use existing HTTP standards for responses. So a response could include a representation of state in any of the formats that we already mentioned.
But it should also include an appropriate HTTP status code. For example, it shouldn't rely on custom error messages alone but should use error codes like 404 and 500, and make good use of the universal standard that all clients should already understand. To illustrate some of the ideas, let's look at the difference between a hypothetical RESTful and non-RESTful API call. In the non-RESTful API call here, we're using POST in passing the name of an operation, DELETE, along with a product ID.
This can work just fine. But compare it to the HTTP request to our hypothetical RESTful API and you can see that the URI identifies a specific resource. The purpose of the request is very clear just by looking at the HTTP verb, DELETE, and it's a little simpler and cleaner too. It's often said that the best way to understand REST is to read Roy Fielding's dissertation. And if you are worried that you are going to end up like this guy, while reading about REST, just know that it's actually a pretty approachable paper and not too lengthy.
You can find it at this URL, at the University of California Irving site. So that gives you a general idea of the main principles behind REST based architecture. In the next video, we'll take a look at building an ASP.net web API that puts some of these principles to use.
- Exploring .NET in general and ASP.NET in particular
- Creating controllers and views
- Working with models and forms
- Managing data
- Creating web APIs
- Establishing connections with SignalR