Web Development

RESTful Web Services: A Tutorial

By M. Vaqqas, September 23, 2014

As REST has become the default for most Web and mobile apps, it's imperative to have the basics at your fingertips.

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 in MyService as in Listing Six:

Caching

Caching is the concept of storing the generated results and using the stored results instead of generating them repeatedly if the same request arrives in the near future. This can be done on the client, the server, or on any other component between them, such as a proxy server. Caching is a great way of enhancing the service performance, but if not managed properly, it can result in client being served stale results.

Caching can be controlled using these HTTP headers:

Header

Application

Date

Date and time when this representation was generated.

Last Modified

Date and time when the server last modified this representation.

Cache-Control

The HTTP 1.1 header used to control caching.

Expires

Expiration date and time for this representation. To support HTTP 1.0 clients.

Age

Duration passed in seconds since this was fetched from the server. Can be inserted by an intermediary component.

Values of these headers can be used in combination with the directives in a Cache-Control header to check if the cached results are still valid or not. The most common directives for Cache-Control header are:

Directive

Application

Public

The default. Indicates any component can cache this representation.

Private

Intermediary components cannot cache this representation, only client or server can do so.

no-cache/no-store

Caching turned off.

max-age

Duration in seconds after the date-time marked in the Date header for which this representation is valid.

s-maxage

Similar to max-age but only meant for the intermediary caching.

must-revalidate

Indicates that the representation must be revalidated by the server if max-age has passed.

proxy-validate

Similar to max-validate but only meant for the intermediary caching.

You have seen some of these headers and directives above in Listing Five. Depending on the nature of the resources, a service can decide the values of these headers and directives. For example, a service providing stock market updates would keep the cache age limit to as low as possible or even turn off caching completely as this is a critical information and users should get the latest results all the time. On the other hand, a public picture repository whose contents do not change so frequently would use a longer caching age and slack caching rules. The server, the client, and any intermediate component between them should follow these directives to avoid outdated information getting served.

Documenting a RESTful Service

RESTful services do not necessarily require a document to help clients discover them. Due to URIs, links, and a uniform interface, it is extremely simple to discover RESTful services at runtime. A client can simply know the base address of the service and from there it can discover the service on its own by traversing through the resources using links. The method OPTION can be used effectively in the process of discovering a service.

This does not mean that RESTful services require no documentation at all. There is no excuse for not documenting your service. You should document every resource and URI for client developers. You can use any format for structuring your document, but it should contain enough information about resources, URIs, Available Methods, and any other information required for accessing your service. The Table below is a sample documentation of MyService. This is a simple and short document that contains all the aspects of MyService and should be sufficient for developing a client.

Service Name: MyService

Address: http://MyService/

Resource

Methods

URI

Description

Person

GET,POST,PUT, DELETE

http://MyService/Persons/{PersonID}

Contains information about a person

{PersonID} is optional

Format: text/xml

Club

GET,POST,PUT

http://MyService/Clubs/{ClubID}

Contains information about a club. A club can be joined my multiple people

{ClubID} is optional

Format: text/xml

Search

GET

http://MyService/Search?

Search a person or a club

Format: text/xml

Query Parameters:

Name: String, Name of a person or a club

Country: String, optional, Name of the country of a person or a club

Type: String, optional, Person or Club. If not provided then search will result in both Person and Cubs

You may also like to document the representations of each resource and provide some sample representations.

Conclusion

REST is a great way of developing lightweight Web services that are easy to implement, maintain, and discover. HTTP provides an excellent interface to implement RESTful services with features like a uniform interface and caching. However, it is up to developers to implement and utilize these features correctly. If we get the basics right, a RESTful service can be easily implemented using any of the existing technologies such as Python, .NET, or Java. I hope this article provides enough information for you to start developing your own RESTful services.

M. Vaqqas is a Software Engineer working on Web technologies for UnitedHealth Group.

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!