This talk is for .NET developers who need a 100 level overview of REST APIs and want to know how to consume some common ones using publicly available tools in .NET. This isn’t for experts or WCF wizards who want to craft their own REST APIs using the WCF Rest Toolkit.
Here’s what you should get out of the talk today:
-Background on REST itself
-An understanding of the high level process for consuming REST APIs
-The principals behind the design of the REST architecture
-A broad understanding of the security issues in REST and why it’s so important
-And a look at some rough examples of how to put popular REST wrapper libraries like RestSharp and Hammock REST into practice.
So REST is everywhere – most major online properties give developers some method of leveraging their content or services via a public REST API.
Facebook, Foursquare, Twitter, Flickr, Twilio, Bing, Google, you name it.
What does REST stand for?
It stands for Representational State Transfer – it’s a method for passing persistent data, or state, to a client for viewing or manipulation.
So what is REST? Well it’s not a standard like SOAP or WSDL.
It’s just an architectural pattern, and any movement towards standardization has been done so in a de facto fashion by REST API authors, not a standards governing body like the IETF.
Here’s the high-level view of consuming REST APIs – you have three actors: the client, which can be anything – a web page, a mobile device, a computer, or anything that can access the internet; you have the Internet itself as an actor; and then finally you have the endpoint on the other side of the network.
The way these interop together is your client issues a request across the network, consisting of an HTTP verb plus a target URI and perhaps some other dimensions found within the realm of hypermedia. The REST endpoint receives the request and in return sends a serialized, MIME-encoded entity across the network. The client receives the entity, deserializes it into a useful object, and proceeds to do something awesome with it.
That’s REST API consumption in a nutshell.
There are four core principals to the design of REST architectures:
The first is that all resources are identifiable – meaning that all of the possible methods, which are themselves resources, you can hit in a REST API are exposed in some manner and those methods can enable you to gain access to the other resources you need to make additional calls, such as authorization tokens.
The second is that all resources can be manipulated – a client has the ability to take a resource, do something to it, and persist the change to the service.
The third principal is that all messages received from a REST service are self-descriptive, meaning that they use a MIME type and can be easily understood by a human.
The final principal is that hypermedia is the engine – which means that REST utilizes the HTTP protocol and the standard “hyperlink” construct as its functional form.
These will all make more sense in the next few slides.
So what are “identifiable” resources in the context of REST – typically we’re referring to URIs which expose endpoints for REST API methods.
Take this method from the Twitter REST API – you have an authority which demarcates the common service point for all methods within this API, you have an API version number which is a good practice for gradually phasing out older versions of REST APIs, you have a method, and then you have the parameters for that method supplied as query string arguments.
Method arguments can also be passed as HTTP headers within a request, but it’s totally up to the people who designed the API you’re working with to determine where, when, and how they’re used in conjunction with other argument types such as query strings and HTTP Verbs.
We already talked about resources from the perspective of service methods themselves, but I also wanted to give you the full landscape of what REST API developers mean when they’re referring to resources. Resources can also mean authentication resources, data from the service itself, and other macro-level resources like API keys and endpoints.
Manipulation of resources – first, I’d like to thank Wikipedia for allowing me to steal this.
Second, this table depicts what the initial REST authors meant by manipulation of resources. The top row shows how an example REST API might refer to a collection of available resources using typical syntax – you might use a method like this for querying a bunch of your user’s Twitter status updates over the past week or two.
Typically you’d use a GET operation for retrieving a list of URIs which describe individual elements in the collection, the PUT verb to actually replace the entire collection, a POST verb to add a new member to the collection, and the DELETE verb to actually remove the entire collection. Obviously how a REST API actually uses these verbs is totally up to the API designer, but in case any of you have the crazy idea of allowing people to make changes to persistent objects on your REST API using GET verbs, bear in mind that accidentally clicking on a link which points to that particular endpoint on your API could result in a lot of data being lost. That’s why it’s a good idea to make developers work a little bit harder to change state by requiring stickier verbs like PUT and POST for operations that change state.
Now if you look at the second row of the table here, it’s the same set of operations but just for a single entity in a collection. And you could in theory extend this out recursively if you wanted to drill down into a collection of collections or something like that. You just keep adding more crap to the end of the URL and hey, your REST API gets that much larger. That’s RESTful behavior, which naturally lends itself to extensibility.
Self Descriptive messages – this is a sample response from the Flickr API. Now, we can’t make sense of all of the details per say, but we can obviously read the message as it’s sent in UTF-8 encoded text and based on the structure of the XML we can get a general idea of what this is for. This is the essence of what the original REST authors meant when they said “self-describing messages.”
Security gets its own big section in this talk as it’s pivotal to what we do as developers who work with user’s data. You’re not merely hitting a remote service endpoint over a network – you’re dealing with users’ private data when you work with most REST APIs, and we need to keep malicious users out the best we can.
