What Is A Restful Api

What is an API? An Application Programming Interface (API) is simply a way of exposing the internal functionality of a service in a safe way. This enables clients to be able to make use of a systems functions without the system having to compromise on security or requiring a client to learn the details of a systems implementation.

One example is the Yahoo Weather API. If I am building an application and want to include some weather information within it, I can simply request this information in the form of a HTTP parameterized query like this:

https://query.yahooapis.com/v1/public/yql?q=select * from weather.forecast where woeid = 44418

The above URI will return an XML response containing all of the weather information for Greater London. I can then parse this XML in my web app or desktop application to display the information I want. I don’t need to know how the underlying system gets the weather information, I simply need to know the correct URI and query to make and let Yahoo take care of the rest.

What is REST? REST stands for REpresentational State Transfer, and is the underlying software architectural style of the World Wide Web (WWW). The term itself was introduced in 2000 by Roy Fielding and was used to design the HyperText Transfer Protocol (HTTP) 1.1 and the Uniform Resource Identifier (URI) protocol. Although it may sound like a relatively new buzzword, the concept of REST has actually been around as long as the Web.

The simple process of entering a URI in to a web browser and receiving a web page is REST in its fundamental form. Whats actually happening underneath is a GET request is sent containing the resource path, the protocol (HTTP 1.1 etc.) and the content type (text/html). A response is then returned (HTTP 1.1 200 OK) containing the resource that was requested in text/html format. If the user previously requested this resource then it is likely it was cached on one or more intermediary devices between the user and the server.

The amazing thing about the Web is that a client does not need to know the underlying structure of a remote system to be able to communicate with it. It simply needs to know the URI of a particular remote resource, the corresponding HTTP verb to use, and the content type it should expect to receive in the response from the server (typically web browsers take care of the last two for us).

What are HTTP verbs? The most commonly used HTTP verbs (methods) are GET and POST, but there are a few lesser known verbs: OPTIONS, DELETE, PUT etc.

I should point out that web browsers typically only support the GET and POST verbs. Although JavaScripts XMLHTTPRequest Object accepts PUT and DELETE also. These verbs can be implemented through the use of JQuery’s $.ajax() method.

In a RESTful API these verbs will correspond to a specific action the client can take against a particular resource that an API is exposing and should directly correlate to a database operation in the following way:

HTTP Verb	CRUD operation
POST	Create
GET	Read
PUT	Update
DELETE	Delete

What makes an API RESTful? At its simplest, an API is RESTful when it adheres to the principles of REST. That is, it must not require the client to know anything about the structure of the API, the server must provide any necessary information the client needs to interact with its API.

A good example of this is a HTML form. The server provides the form to the clients web browser which will contain the resource URI and the data it requires as form fields. The client doesn’t know in advance what information it should provide in the form or the resource location to submit it too, this information was provided entirely by the server.

An API is also RESTful when it adheres to HTTP standard verbs and resources, as described above. The resource location will usually correlate to an entity, upon which actions can be performed through the use of HTTP verbs and specified parameters.

What about SOAP? Simple Object Access Protocol (SOAP) is an alternative API framework that REST has all but replaced. SOAP is more restrictive than REST because it only permits the XML data format, it is not cache-able, and REST performs faster through its support of JSON which also makes it a better fit for browser-based clients where JSON parsing is easiest.

RESTful API example In this example I will demonstrate how to implement a basic RESTful API to manipulate User data using the Jersey JAX-RS Java framework.

User request/response.

URI	HTTP verb	Response
/user	GET	201
/user	POST	201 User successfully created.
/user/delete	POST	201 User successfully deleted.
/user/update	POST	201 User successfully updated.

In the above example you will notice that the getUser()and createUser() methods are mapped to the same URI, but respond to different HTTP verbs. Because we have to rely on the POST(not DELETE) verb to call our deleteUser() method we have to assign an extension to the URI to differentiate it to the createUser() mapping.

Summary

• An API is a way of exposing the functionality of a system so it can be utilised by other programs.
• An API is RESTful when it use URI's, HTTP verbs and response codes.
• Web browsers only allow the GET and POST verbs to be used.
• The same URI can be used to perform different operations on an entity, provided different verbs are used.