AzureDays

Everything is a resource in REST. As you learned in Choosing Between RESTful Web Service, SOAP, Representational State Transfer (REST) is an architecture style or design pattern for creating web services which allow anything connected to a network to something else on the network using Hypertext Transfer Protocol (HTTP).

In this post, you will learn the how to define your resource identifier. In the following post, you will learn how to use the HTTP verbs and response codes. And along the way you will learn many of the principles of a good RESTful API.

Let me second what As Thomas Hunter II writes:

The easier your API is to consume, the more people that will consume it.

The Interview Question

Developers and architects are asked to design a sample REST API. I had seen RESTful APIs and thought I’d be able to nail the answer. The right answer includes resources, request verbs, request headers, request body, response body, and response status codes.

There is a big difference between something that looks like REST and something that is RESTful. When you combine your verbs and nouns into a URL, you are using a remote procedure call (RPC). RPC is a an API style where endpoints perform arbitrary actions that are not necessarily tied to a particular resource. Typically, RPC service methods combine the noun and verb in one method name (e.g. GetPosts or SendInvoice).

If you’re using ASMX or WCF, you’re probably using the RPC approach.

RPC vs REST

Fundamental problem with RPC is coupling. RPC clients become tightly coupled to service implementation in several ways and it becomes very hard to change service implementation without breaking clients:

• Clients are required to know procedure names;
• Procedure parameters order, types and count matters. It’s not that easy to change procedure signatures(number of arguments, order of arguments, argument types etc…) on server side without breaking client implementations;
• RPC style doesn’t expose anything but procedure endpoints + procedure arguments. It’s impossible for client to determine what can be done next.

REST in Web API

In the context of ASP.NET Web API, the key distinction between REST and RPC is that in a RESTful approach your API consumers interact with public methods corresponding to HTTP verbs (e.g. Get() or Delete(int Id)). If a method doesn’t map to an HTTP verb, it doesn’t fit into a RESTful API.

You will learn more about the verbs in the next post, but in this post, you will learn about the nouns (resources, headers, and body).

Parts of the RESTful API

There are several key implementation details with HTTP that you should be aware of:

• Resources – REST uses addressable resources to define the structure of the API. These are the URLs you use to get to pages on the web, for example https://management.core.windows.net/7777777/services/hostedservices is a resource.
• Request Verbs – These describe what you want to do with the resource. A browser typically issues a GET verb to instruct the endpoint it wants to get data, however there are many other verbs available including things like POST, PUT and DELETE. See the full list at HTTP Method Definitions.
• Request Headers – These are additional instructions that are sent with the request. These might define what type of response is required or authorization details. See the full list at HTTP Header Field Definitions.
• Request Body – Data that is sent with the request. For example a POST (creation of a new item) will required some data which is typically sent as the request body in the format of JSON or XML.
• Response Body – This is the main body of the response. If the request was to a web server, this might be a full HTML page, if it was to an API, this might be a JSON or XML document.
• Response Status codes – These codes are issues with the response and give the client details on the status of the request. See the full list at HTTP Status Code Definitions

URI or URL?

A RESTful API exposes its data as resources (or nouns) at URIs that clients interact with via HTTP methods like GET and POST (or verbs).

URI

A URI identifies a resource either by location or name. More often than not, most of us use URIs that defines a location to a resource. However, a URI does not have to specify the location of a specific representation. Citing and example of a W3C URI for their home image, they use the following URI: http://www.w3.org/Icons/w3c_home. Note the absence of a file extension. The URI for the w3c_home image is still universally unique, but it does not specify the specific representation of the image (either a GIF, PNG, or JPG). The selection of the representation can be determined by the web server through HTTP content negotiation. The Apache HTTPD server has had excellent support for content negotiation for many years. Oddly, few sites take advantage of HTTP content negotiation. The W3C is one web application that makes heavy use of URIs and content negotiation.

URL

A URL is a URI but a URI is not a URL. A URL is a specialization of URI that defines the network location of a specific representation for a given resource.

A URL is a URI but a URI is not a URL. A URL is a specialization of URI that defines the network location of a specific representation for a given resource. Taking the same W3C example, there are actually 2 representations available for the w3c_home resource:

• http://www.w3.org/Icons/w3c_home.gif
• http://www.w3.org/Icons/w3c_home.png

These URIs also define the file extension that indicates what content type is available at the URL. Through content negotiation, the web server will forward the user agent to the proper type, depending on the client’s capabilities, when the URI http://www.w3.org/Icons/w3c_home is accessed.

RESTful API Resources

REST uses addressable resources to define the structure of the API. These are the URIs that define what object you want to take some action on:

Request Header

Headers are name/value pairs that appear in both request and response messages. The name of the header is separated from the value by a single colon.

Here is an example of a header to localhost:

Content Negotiation

The HTTP specification (RFC 2616) defines content negotiation as “the process of selecting the best representation for a given response when there are multiple representations available.” The primary mechanism for content negotiation in HTTP are these request headers:

• Accept: Which media types are acceptable for the response, such as “application/json,” “application/xml,” or a custom media type such as “application/vnd.example+xml”
• Accept-Charset: Which character sets are acceptable, such as UTF-8 or ISO 8859-1.
• Accept-Encoding: Which content encodings are acceptable, such as gzip.
• Accept-Language: The preferred natural language, such as “en-us”.

The server can also look at other portions of the HTTP request. For example, if the request contains an X-Requested-With header, indicating an AJAX request, the server might default to JSON if there is no Accept header.

You can learn more at Content Negotiation in ASP.NET Web API.

OpenID Connect

Once you obtain the OpenID Connect token, you will typically provide the initial access token in the HTTP request header, such as.

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Request Body

Resources can have different representations. In the case of the Azure Service Management API, you can create a cloud service. You post to a particular URI, add the correct request headers, and then provide a body. In the case of Azure, you provide XML specifying that you want to create a hosted service and then the details of that service.

Next Up

In our next post, you will learn how to use HTTP Verbs and how to get information in the response.

Getting Started

To get started with Web API, I’d recommend you initially take a look at Martin Kearn’s video to help you creates a very simple web API: http://aka.ms/mk-filenewapivideo

Then you should take a look on the official ASP.net sub site which has plenty of tutorials, examples and videos: http://www.asp.net/web-api

References

• REST vs JSON-RPC?
• REST vs. RPC in ASP.NET Web API? Who cares; it does both
• Principles of good RESTful API Design
• URI vs. URL: What’s the difference?
• Creative Commons Book on HTTP API Design
• Designing a RESTful Web API
• An Introduction To RESTful Services With WCF
• Introduction to REST and .net Web API”