Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

Many developers are exploring how to build good Web APIs. The most common current approach is to build APIs that conform to the REST architecture.

Discussions about how best to adopt a RESTful approach often focus on server-side issues, such as how to design resources and how to make the correct usage of HTTP. As a learning exercise, existing API designs are often evaluated to determine how RESTful they are using tools like the Richardson Maturity Model.

Any good RESTful API — Level 3 in the Richardson Model — will:

  • Have an entry point (“service description”) into the API for clients
  • Use well-defined standard or custom media types for exchanging messages
  • Use hypertext (links) in messages to advertise how a client can traverse the API functionality

What if we think about REST from a client-side perspective? Can that help us understand the benefits of a hypermedia approach?

In the following sections we will look at some initial “do’s and don’ts” geared toward building good RESTful clients.

Avoid URI Construction

A RESTful API will offer links that reference resources in the application. A request for a user list might be presented as follows:

Here a user has an identifier, a name, and related resources (“home”, “feed”) that are referenced via links. The media type will define the meaning of these links.

Inspecting the URLs we can see that the homepage and feed links can be constructed from the id. We might be tempted to hard-code some knowledge of this in our application. But a RESTful client must never do this. Clients should only construct URIs using controls, e.g. a form, provided by the server.

RESTful clients should assume that URLs can change at any time even between requests. URLs could change as part of a server upgrade, reconfiguration, or even as part of a load-balancing strategy. A robust client will cleanly adapt to changes as it moves across the surface of an API, following links presented by the server.

Similarly, a client must never extract meaningful data from a URL. If data, like the id in the above example, is intended to be public, then it will be exposed in the message, not the URL. Everything else must be treated as implementation details.

Always Bootstrap Into An API

A REST API is likely to have an entry point or “service description” that advertises useful starting resources, e.g. the URLs for a list of users, tags and registrations:

A media type might also define additional controls that describe how to submit searches, such as how to find a user by name.

The temptation may be to hard-code these links or definitions into your application, as a configuration or via code generation. But if the server URLs change then the code will break, requiring an application change, with a release and install cycle, which will cost time and money. When was the last time you upgraded a browser because a link or form was changed on a website?

Applications should always bootstrap into an API. The bootstrap will be a link provided by a user or even dynamically discovered using a well-known URI.

Tolerate Message and Media Type Changes

It’s not only URLs that may change: a server might start publishing more data or start supporting new media types.

Clients that obey Postel’s Law will ignore additional data or links in messages, allowing a server to begin offering new functionality. This allows for a gradual and distributed evolution of the clients: your application can then be upgraded if, and when, the new functionality becomes useful.

Clients should also request only those media types it understands. A RESTful API will use standard or custom media types, e.g. Atom (application/atom+xml) or custom types like application/vnd.github+json. Initially a server might only support a single specific type, but over time it may add additional types. The default response format might even change, for instance to adopt an industry standard.

Clients should plan for evolution and be explicit in requesting those formats they can process. HTTP content negotiation provides the means for clients to request formats in order of preference:

Media types of responses should also be checked: do not assume that what was requested has actually been returned.

Generic clients, intended for use with several APIs, might even support more media types than the server. The separate evolution of client and server components is key to REST.

Use A Good Client Library

API documentation often lists server-side resources, media types and typical response codes. This is useful and necessary documentation, but clients shouldn’t be implementing to use a profile of HTTP. A good HTTP client library will ensure applications cleanly handle redirects, rate-limiting, and take advantage of caching directives. Just like servers, RESTful clients must also make proper use of HTTP.

Many HTTP clients use a default User-Agent header that masks which application is actually making the request. Adding a clear User-Agent to advertise an application will be useful for API developers looking to track usage or identify problem clients.


REST provides the ability to create truly flexible APIs that can be more easily versioned and extended. But this requires both server and client components to follow the principles of REST. Brittle clients will hamper the ability of API developers to innovate and expose new functionality, leading to the type of controlled and often catastrophic versioning issues seen with Twitter and Facebook. Client applications should assume a server will be constantly evolving, tolerating changes in URL structure, message contents and media types.

For more details about REST, see the ebooks referenced below.

Safari Books Online has the content you need

REST continues to gain momentum as the best method for building web services, leaving many web architects to consider whether and how to include this approach in their SOA and SOAP-dominated world. Rest in Practice offers a down-to-earth explanation of REST, with techniques and examples that show you how to design and implement integration solutions using the REST architectural style.
The basic rules of REST APIs – “many nouns, few verbs, stick with HTTP” – seem easy, but that simplicity and power require discipline to work smoothly. REST API Design Rulebook provides the next steps for implementing complex REST projects on simple and extensible foundations.
SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST is the first comprehensive tutorial and reference for designing and building RESTful services as part of service-oriented solutions and in conjunction with service-oriented architecture (SOA). This book demonstrates that REST is not only a suitable medium for building truly service-oriented solutions, but also that the service-oriented architectural model is a necessary foundation for REST technology architectures to realize their full business potential.

About the author

Leigh Dodds is a freelance consultant specializing in Linked Data, Open Data and API development. Passionate about the web, open standards, and open source he enjoys exploring how to apply new technologies to create interesting products. He’s also quite fond of gaming, Lego, Minecraft and a good beer. You can reach Leigh on
Github: or on Twitter: @ldodds.

Tags: Atom, Client, HTTP, Postel's Law, REST, RESTful API, Richardson Model,

One Response to “REST from a Client Perspective”