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 Person
s can be part of a Club
, then a Club
can be represented in MyService
as in Listing Six:
Listing Six: A Club with links to Persons.
<Club> <Name>Authors Club</Name> <Persons> <Person> <Name>M. Vaqqas</Name> <URI>http://MyService/Persons/1</URI> </Person> <Person> <Name>S. Allamaraju</Name> <URI>http://MyService/Persons/12</URI> </Person> </Persons> </Club>
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 and time when this representation was generated. |
|
Date and time when the server last modified this representation. |
|
The HTTP 1.1 header used to control caching. |
|
Expiration date and time for this representation. To support HTTP 1.0 clients. |
|
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 |
|
The default. Indicates any component can cache this representation. |
|
Intermediary components cannot cache this representation, only client or server can do so. |
|
Caching turned off. |
|
Duration in seconds after the date-time marked in the |
|
Similar to |
|
Indicates that the representation must be revalidated by the server if |
|
Similar to |
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 |
|
http://MyService/Persons/{PersonID} |
Contains information about a person { Format: text/xml |
Club |
|
http://MyService/Clubs/{ClubID} |
Contains information about a club. A club can be joined my multiple people { Format: text/xml |
Search |
|
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.