REST and JSON best practices

For a long time I've been struggling with REST API conventions. REST was -and is- a difficult concept which has been poorly understood for a long time. Nowadays there are lots of excellent style guides. Below I've gathered some guidelines and best practices from various sources.

In all guidelines I've assumed the REST service returns JSON because it is the most common format these days. Most guidelines should work for other formats (XML in particular) as well.

HTTP methods

HTTP result codes

The following list contains the more relevant REST-service HTTP status codes. A common mistake is to return a 200 OK when something went wrong. REST services ought to utilize what HTTP has on offer. 200 OK: when a request was processed successfully, for example when a partial update succeeded.

URL format

Response body

JSON/REST API documentation (*)

(*) Most JSON/REST API style guides stress you should put in the effort to make understandable error response messages. I tend to disagree; a custom error code has sufficed in many applications for decades, why not for JSON/REST services? This avoids the issue of system error message internationalization and you need proper JSON/REST API documentation anyway because JSON/REST lacks a schema definition. Without documentation any service constraints will be a matter of development trial & error (which makes for an unhappy programmer).

Some sources I've bookmarked about these subjects: