RESTful Web APIs book by Leonard Richardson and Mike Amundsen, with a forward by Sam Ruby. ISBN:1449358063 https://www.crummy.com/writing/RESTful-Web-APIs/

• later than RESTful Web Services

Excerpts

Introduction

Duplication of Effort

An API released today will be named after the company that hosts it. We talk about the “Twitter API,”

Of course, Twitter, Facebook, and Google are big companies that compete with each other. They don’t want to make it easy for you to learn their competitors’ APIs. But small companies and nonprofits do the same thing. They design their APIs as though nobody else had ever had a similar idea

57 microblogging APIs

The obvious solution would be to create a standard for microblogging APIs. But there already is a standard that would work just fine: the Atom Publishing Protocol (Atom Standards). It was published in 2005, and almost nobody uses it.

Hypermedia Is Hard

What’s Not in This Book

RESTful Web Services focused heavily on breaking down your business requirements into a set of interlinked resources. My experience since 2007 has convinced me that thinking of API design as resource design is a very effective way to avoid thinking about hypermedia. This book takes a different approach, focusing on representations and state transitions rather than resources.

That said, the resource design approach is certainly valid. For advice on moving in that direction, I recommend RESTful Web Services Cookbook by Subbu Allamaraju

Chapter 10. The Hypermedia Zoo

My goal is to give you a sense of the many forms hypermedia can take, and to show how many times we’ve tackled the basic problems of representing it. The hypermedia zoo is so full that you probably don’t need to define a brand new media type for your API. You should be able to pick an existing media type and write a profile for it.

Problem Detail Documents

Media type: application/api-problem+json

Described in: Internet-Draft “draft-nottingham-http-problem” (Changed to https://datatracker.ietf.org/doc/rfc7807/)

A problem detail document describes an error condition. It uses structured, human-readable text to add custom semantics to HTTP’s status codes. It’s a simple JSON format designed to replace whatever one-off format you were thinking of designing to convey your error messages

Appendix A. The Status Codex

In the world of APIs, then, HTTP response codes become very important

That said, some of the HTTP status codes are completely useless

In this appendix, I give a brief explanation of each status code, with tips on when to use it in your APIs, and my personal opinion as to how important it is to API design.

I also list which HTTP response headers, and what kind of entity-body, the server ought to send along with a response code

I’ll cover all 41 codes mentioned in RFC 2616, even though some of them (mainly the ones to do with proxies) are a little beyond the scope of this book. I’ll also cover a few status codes defined in other RFCs, notably RFC 6585, the aptly named “Additional HTTP Status Codes.”

Problem Detail Documents

In Chapter 10, I mentioned problem detail documents—short hypermedia documents that give a human-readable explanation of an HTTP status code. Don’t forget about these! You can use them to add API-specific details to a generic status code like 400

If your representation format has a slot for error reporting, the way Collection+JSON does, you probably don’t need problem detail documents

Families of Status Codes

Four Status Codes: The Bare Minimum

Four Status Codes: The Bare Minimum

200 (OK)

301 (Moved Permanently)

400 (Bad Request)

500 (Internal Server Error)

If I could add just two more, they would be different kinds of client errors: 404 (Not Found) and 409 (Conflict).

When you need to give more detail, you can adopt another status code from the big list, or provide a problem detail document

1xx: Informational

2xx: Successful

200 (OK)

200 (OK) Importance: Very high.

201 (Created)

201 (Created) Importance: High.

202 (Accepted)

202 (Accepted) Importance: Medium.

The client’s request can’t or won’t be handled in real time. It will be processed later

asynchronous action

Response headers: The pending request should be exposed as some kind of resource so the client can check up on it later

Retry-After: The Retry-After header can be used

204 (No Content)

204 (No Content) Importance: High.

The server may also send 204 in response to a GET request. This means that the resource requested exists, but has an empty

204 is often in-browser JavaScript applications. It lets the server tell the client that its input was accepted, but that the client shouldn’t change any UI elements

206 (Partial Content)

206 (Partial Content) Importance: Very high for APIs that support partial GET, low otherwise.

3xx: Redirection

This is the trickiest set of response codes, because 301 (Moved Permanently), 302 (Found), 303 (See Other), and 307 (Temporary Redirect), are all very similar

300 (Multiple Choices)

300 (Multiple Choices) Importance: Low

301 (Moved Permanently)

301 (Moved Permanently) Importance: Medium

It wants the client to take note of the new URL and use it in future requests.

302 (Found)

302 (Found) Importance: Very important to know about, especially when writing clients. I don’t recommend using it.

This response code is still in wide use, but it’s ambiguous, and I recommend that your servers send 303, 307, and 308 instead

303 (See Other)

303 (See Other) Importance: High

instead of the server sending a response document, it’s sending the client the URL of a response document. This may be the URL of a static status message, or of some more interesting resource

304 (Not Modified)

304 (Not Modified) Importance: High

307 (Temporary Redirect)

307 (Temporary Redirect) Importance: High.

For GET requests, where the only thing being requested is that the server send a representation, this status code is identical to 303 (See Other). A typical case where 307 is a good response to a GET is when the server wants to send a client to a mirror site

But for POST, PUT, and DELETE requests, where the server is expected to take some action in response to the request, this status code is significantly different from 303.

A 303 in response to a POST, PUT, or DELETE means that the operation has succeeded but that the response entity-body is not being sent along with this request

A 307 in response to a POST, PUT, or DELETE means that the server has not even tried to perform the operation. The client needs to resubmit the entire request to the URL in the Location header

4xx: Client-Side Error

4xx: Client-Side Error

Problem details (see Chapter 10) are most useful for the 4xx series of codes

400 (Bad Request)

400 (Bad Request) Importance: Very high

It’s commonly used when the client submits a representation along with a PUT or POST request, and the representation is in the right format, but it doesn’t make any sense

401 (Unauthorized)

401 (Unauthorized) Importance: High

404 (Not Found)

404 (Not Found) Importance: High

the server can’t map the client’s URL to a resource. Compare 410 (Gone), which is slightly more helpful.

409 (Conflict)

409 (Conflict) Importance: Very high.

The client tried to create an impossible or inconsistent resource state on the server.

A collection-based API may allow a client to DELETE an empty collection, but send 409 when the client tries to DELETE a collection that still contains members

410 (Gone)

410 (Gone) Importance: Medium.

Unlike the permanent redirect, the 410 offers no replacement for the bad URL: it’s just gone

412 (Precondition Failed)

412 (Precondition Failed) Importance: Medium

A common precondition is If-Unmodified-Since.

Without the precondition, the client might overwrite someone else’s changes without realizing it, or might cause a 409 (Conflict).

429 (Too Many Requests)

429 (Too Many Requests) Importance: Medium

A server is allowed to simply ignore requests that violate the rate limiting policy, rather than respond to each of them with a 429

5xx: Server-Side Error

5xx: Server-Side Error

problems on the server side. These codes usually mean the server is not in a state to carry out the client’s request or even see whether it’s correct, and that the client should retry its request later

500 (Internal Server Error)

500 (Internal Server Error) Importance: High.

503 (Service Unavailable)

503 (Service Unavailable) Importance: Medium to high.

This status code means that the HTTP server is up, but the application underlying the API isn’t working properly. The most likely cause is resource starvation

Appendix B. The Header Codex

Custom HTTP Headers

In RESTful Web Services, I gave some advice for when to define a custom HTTP header and what to name it. Over the past few years, I’ve changed my mind about both of these things. You probably shouldn’t create a new HTTP header at all.

a lot of the use cases for new HTTP headers no longer apply. Hypermedia data formats are more numerous and more flexible than they were just a few years ago.