The REST API Design Handbook

by George Reese

You have one URI with a finite set of verbs you can use to manipulate it and its representations. The server doesn’t care how the client displays the resource or enables a user to interact with it and the client doesn’t care what the “real” resource is one the server or the technologies used to manipulate or store it. In case of an error, you also have a finite set of error codes that you need to be able to understand. The exact same ideas should apply in an API context. Your API should be defined in terms of POST, GET, PUT, DELETE (and maybe other) HTTP verbs using HTTP status codes. Unfortunately, most “RESTful” APIs don’t do any of this. In fact, the biggest misconception is that you can call your API RESTful if its delivering XML or JSON over HTTP. And that misconception and the resulting proliferation of horrible APIs is likely the source of RESTafarian irritation with the application of the term “RESTful” in an API context. But let’s be brutally honest. Most interactive systems don’t follow this model either. Common web interaction models include: • Performing a GET from one URI and then PUT to another URI • Or, more likely, executing a POST for that update against the second URI • Doing a GET against one URI to perform one kind of operation on a resource (e.g. change password) and then doing another GET against a second URI to perform another kind of operation (change phone number) on the same resource There are a lot of reasons why systems are designed this w...