On the heels of an interesting REST discussion at InfoQ there is an interesting post from George Reese - The Good, the Bad, and the Ugly of REST APIs, discussing many Dos and Don’ts of REST APIs development.
Among good practices for REST API creation, Reese emphasizes the following:
- Map your API model to the way your data is consumed, not your data/object model.
The data in your API calls should not look like highly normalized representations of database tables. They should represent a model of the data in a way that makes sense to API consumers.
This is similar to the SOA principle of separating messaging model from the underlying data access model
- Meaningful error messages help a lot. When building an API, it is necessary
to think about all the mistakes people can make when learning to use your API,
returning a detailed explanation of what exactly was done wrong. Some good examples of such messages are presented in a great slide show.
- Providing solid API documentation reduces need for external help.
Solid API documentation enables an individual to both understand the simple examples that help them get started as well as the complex ways in which they can leverage the API to accomplish advanced tasks
- Use an appropriate security APIs. For example, Reese points out that OAuth authentication, often used with REST, works well when an API provides a target content for the browser, but is rarely applicable for system-to-system interaction. More discussion on securing REST APIs can be found at "RESTful API Authentication Schemes"
- REST is good, SOAP is bad. Reese claims that
SOAP is absurdly complex to implement and support when your target consumers use many different programming languages
He further assers that
JSON is good, XML is bad
so REST - supporting JSON is better than SOAP enforcing XML - statement, that was directly debated by Gerald Loeffler’ recent comment on "Is REST Successful in the Enterprise?".
... without contrasting and comparing technologies on a purely technical basis we would lose the rigor that any technical domain requires... as people become immersed in one way of seeing the world (you might call it an ideology; such as WS-* or REST, or statically typed or dynamically typed) they inevitable come to see it as the truth - it becomes so obviously true. But it isn't: it's just one way of making sense and reasoning about what's out there (with particular characteristics and properties - which is why we (also) need the purely technical debates). Sadly, in software development, truth claims for one's own viewpoint often end in insults against the opponents: they "don't 'get it".
The bad (and ugly) practices identified by Reese include:
- Throttling is a terrible thing to do.
If you are going to use throttling... you need to implement some very intelligent throttling that can a) recognize legitimate traffic like testing and regular polling and b) minimize the negative impact of false positives. Avoid limits based on "wild ass guesses" and consult with customers who might be impacted.
- Chatty APIs suck. A chatty API, as defined by Reese, is any API that requires consumer to do more than a single call to perform a single, common operation. The details of what constitutes chatty, of course, depend on what people might reasonably want to do with the API.
- Returning HTML in response. Reese suggests that the response from a service should always be a valid JSON/XML even when it can't talk to the API server.
If an API consumer EVER sees HTML, you are doing something very, very wrong.
- Side-effects to 500 errors are evil. An API should always make sure that calls that generate 500 errors are idempotent - rollback any changes that might have occurred in the process of generating them.
Reese’s blog provides a set of very solid best practices on REST APIs implementation, describing not only Dos and Don’ts, but also Whys - the rationale behind some things being good or bad. These best practices are not REST specific - they do not talk about REST design or defining resources or choosing of proper parameters passing mechanism - they are good design practices for any API type.