English | 2013 | ISBN: 978-1-4493-5806-8 | 404 Pages | PDF, EPUB | 14 MB
The popularity of REST in recent years has led to tremendous growth in almost-RESTful APIs that don’t include many of the architecture’s benefits. With this practical guide, you’ll learn what it takes to design usable REST APIs that evolve over time. By focusing on solutions that cross a variety of domains, this book shows you how to create powerful and secure applications, using the tools designed for the world’s most successful distributed computing system: the World Wide Web.
You’ll explore the concepts behind REST, learn different strategies for creating hypermedia-based APIs, and then put everything together with a step-by-step guide to designing a RESTful Web API.
- Examine API design strategies, including the collection pattern and pure hypermedia
- Understand how hypermedia ties representations together into a coherent API
- Discover how XMDP and ALPS profile formats can help you meet the Web API “semantic challenge”
- Learn close to two-dozen standardized hypermedia data formats
- Apply best practices for using HTTP in API implementations
- Create Web APIs with the JSON-LD standard and other the Linked Data approaches
- Understand the CoAP protocol for using REST in embedded systems
A Simple API
How much can we learn from this? Well, every HTTP response can be split into three parts:
The status code, sometimes called the response code
This is a three-digit number that summarizes how the request went. The response code is the first thing an API client sees, and it sets the tone for the rest of the response. Here, the status code was 200 (OK). This is the status code a client hopes for—it means that everything went fine.
In Appendix A, I explain all of the standard HTTP response codes, as well as several useful extensions.
The entity-body, sometimes called just the body
This is a document written in some data format, which the client is expected to understand. If you think of a GET request as a request for a representation, you can
think of the entity-body as the representation (technically, the entire HTTP response is the ‘representation’, but the important information is usually in the entitybody). In this case, the entity-body is the huge document at the end of the response, the one full of curly brackets.
The response headers
These are a series of key-value pairs describing the entity-body and the HTTP response in general. Response headers are sent between the status code and the entitybody. In Appendix B, I explain all the standard HTTP headers and many useful extensions.
The most important HTTP header is Content-Type, which tells the HTTP client how to understand the entity-body. It’s so important that its value has a special name. We say the value of the Content-Typeheader is the entity-body’s media type. (It’s also called the MIME typeor the content type. Sometimes “media type” is hyphenated: media-type.)
On the part of the Web that human beings can see with their web browsers, the most common media types are text/html(for HTML) and image types like image/jpeg. Here, the media type is one you probably haven’t seen before: application/vnd.collection+json.
This indicates that the resource state is so volatile that the representation probably become obsolete during the time it took to send it. Setting Cache-Controlwhen you serve a representation requires that you make a judgment call on how often a representation will change. If you get this wrong, it can lead to your users having data that’s out of date. For representations that consist entirely of hypermedia controls, representations that only change when you upgrade your API implementation, it makes sense to set maxagepretty high. Or you can use…
Sometimes you just don’t know when a resource’s state will change. (Collection-type resources are the worst for this.) It might change all the time, or it might change so rarely that you can’t estimate how often a change happens. Either way, you can’t decide on a value for max-age, so you can’t tell the client to stop making requests for that resource for a while. Instead, you can let the client make its request whenever it wants, and eliminate the server’s responseif nothing has changed.