RESTful Web Services: A Tutorial--reference

The response code?200 OK?means that everything went well and the response message body contains a valid representation of the resource I requested. In this case,the representation is an HTML document that is declared by?Content-Type?header in the response header. The headers in the message are self explanatory,but I will discuss some of them later in this article. There are?. You can catch and inspect such HTTP requests and responses using a free tool called?.

Addressing Resources

REST requires each resource to have at least one URI. A RESTful service uses a directory hierarchy like human readable URIs to address its resources. The job of a URI is to identify a resource or a collection of resources. The actual operation is determined by an HTTP verb. The URI should not say anything about the operation or action. This enables us to call the same URI with different HTTP verbs to perform different operations.

Suppose we have a database of persons and we wish to expose it to the outer world through a service. A resource?person?can be addressed like this:

http://MyService/Persons/1

This URL has following format:?Protocol://ServiceName/ResourceType/ResourceID

Here are some important recommendations for well-structured URIs:

• Use plural nouns for naming your resources.
• Avoid using spaces as they create confusion. Use an?_?(underscore) or?–?(hyphen) instead.
• A URI is case insensitive. I use camel case in my URIs for better clarity. You can use all lower-case URIs.
• You can have your own conventions,but stay consistent throughout the service. Make sure your clients are aware of this convention. It becomes easier for your clients to construct the URIs programmatically if they are aware of the resource hierarchy and the URI convention you follow.
• A cool URI never changes; so give some thought before deciding on the URIs for your service. If you need to change the location of a resource,do not discard the old URI. If a request comes for the old URI,use status code?300?and redirect the client to the new location.
• Avoid verbs for your resource names until your resource is actually an operation or a process. Verbs are more suitable for the names of operations. For example,a RESTful service should not have the URIs?http://MyService/FetcthPerson/1?orhttp://MyService/DeletePerson?id=1.

Query Parameters in URI

The preceding URI is constructed with the help of a query parameter:

http://MyService/Persons?id=1

The query parameter approach works just fine and REST does not stop you from using query parameters. However,this approach has a few disadvantages.

• Increased complexity and reduced readability,which will increase if you have more parameters
• Search-engine crawlers and indexers like Google ignore URIs with query parameters. If you are developing for the Web,this would be a great disadvantage as a portion of your Web service will be hidden from the search engines.

The basic purpose of query parameters is to provide parameters to an operation that needs the data items. For example,if you want the format of the presentation to be decided by the client. You can achieve that through a parameter like this:

http://MyService/Persons/1?format=xml&encoding=UTF8

or

http://MyService/Persons/1?format=json&encoding=UTF8

Including the parameters?format?and?encoding?here in the main URI in a parent-child hierarchy will not be logically correct as they have no such relation:

http://MyService/Persons/1/json/UTF8

Query parameters also allow optional parameters. This is not otherwise possible in a URI. You should use query parameters only for the use they are intended for: providing parameter values to a process.

GET?is probably the most popular method on the Web. It is used to fetch a resource.

HEAD?returns only the response headers with an empty body. This method can be used in a scenario when you do not need the entire representation of the resource. For example,?HEADcan be used to quickly check whether a resource exists on the server or not.

The method?OPTIONS?is used to get a list of allowed operations on the resource. For example consider the request:

<pre class="brush: text; html: collapse;">OPTIONS http://MyService/Persons/1 HTTP/1.1
HOST: MyService

The service after authorizing and authenticating the request can return something like:

<pre class="brush: text; html: collapse;">200 OK
Allow: HEAD,GET,PUT

The second line contains the list of operations that are allowed for this client.

You should use these methods only for the purpose for which they are intended. For instance,never use?GET?to create or delete a resource on the server. If you do,it will confuse your clients and they may end up performing unintended operations. To illustrate,this let's consider this request:

<pre class="brush: text; html: collapse;">GET http://MyService/DeletePersons/1 HTTP/1.1
HOST: MyService

By HTTP 1.1 specification,a?GET?request is supposed to fetch resources from the server. But it is very easy to implement your service such that this request actually deletes a?Person. This request may work perfectly,but this is not a RESTful design. Instead,use the?DELETE?method to delete a resource like this:

<pre class="brush: text; html: collapse;">DELETE http://MyService/Persons/1 HTTP/1.1
HOST: MyService

REST recommends a uniform interface and HTTP provides you that uniform interface. However,it is up to service architects and developers to keep it uniform.

Difference between PUT and POST

The short descriptions of these two methods I provided above are almost the same. These two methods confuse a lot of developers. So let's discuss these separately.

The key difference between?PUT?and?POST?is that?PUT?is idempotent while?POST?is not. No matter how many times you send a?PUT?request,the results will be same.?POST?is not an idempotent method. Making a?POST?multiple times may result in multiple resources getting created on the server.

Another difference is that,with?PUT,you must always specify the complete URI of the resource. This implies that the client should be able to construct the URI of a resource even if it does not yet exist on the server. This is possible when it is the client's job to choose a unique name or ID for the resource,just like creating a user on the server requires the client to choose a user ID. If a client is not able to guess the complete URI of the resource,then you have no option but to use?POST.

Statelessness

A RESTful service is stateless and does not maintain the application state for any client. A request cannot be dependent on a past request and a service treats each request independently. HTTP is a stateless protocol by design and you need to do something extra to implement a stateful service using HTTP. But it is really easy to implement stateful services with current technologies. We need a clear understanding of a stateless and stateful design so that we can avoid misinterpretation.

A stateless design looks like so:

Request1:?GET http://MyService/Persons/1 HTTP/1.1

Request2:?GET http://MyService/Persons/2 HTTP/1.1

Each of these requests can be treated separately.

A stateful design,on the other hand,looks like so:

Request1:?GET http://MyService/Persons/1 HTTP/1.1

Request2:?GET http://MyService/NextPerson HTTP/1.1

To process the second request,the server needs to remember the last?PersonID?that the client fetched. In other words,the server needs to remember the current state — otherwise Request2 cannot be processed. Design your service in a way that a request never refers to a previous request. Stateless services are easier to host,easy to maintain,and more scalable. Plus,such services can provide better response time to requests,as it is much easier to load balance them.

Links Between Resources

A resource representation can contain links to other resources like an HTML page contains links to other pages. The representations returned by the service should drive the process flow as in case of a website. When you visit any website,you are presented with an index page. You click one of the links and move to another page and so on. Here,the representation is in the HTML documents and the user is driven through the website by these HTML documents themselves. The user does not need a map before coming to a website. A service can be (and should be) designed in the same manner.

Let's consider the case in which a client requests one resource that contains multiple other resources. Instead of dumping all these resources,you can list the resources and provide links to them. Links help keep the representations small in size.

For an example,if multiple?Persons can be part of a?Club,then a?Club?can be represented inMyService?as in Listing Six:

Listing Six: A Club with links to Persons.