REST API best practices

Vinay Sahni of Enchant writes Best Practices for Designing a Pragmatic RESTful API, a complete, current best practices article on REST APIs, chock full of explanation, examples and real APIs from top web sites. Enchant itself is a good example how to document a REST API. Vinay has been writing a long series of articles on REST APIs, plenty of chewy links for further reading. Main points:

• Key requirements for the API
• Use RESTful URLs and actions
• SSL everywhere - all the time
• Documentation
• Versioning
• Result filtering, sorting & searching
• Limiting which fields are returned by the API
• Updates & creation should return a resource representation
• Should you HATEOAS?
• JSON only responses
• snake_case vs camelCase for field names
• Pretty print by default & ensure gzip is supported
• Don't use an envelope by default, but make it possible when needed
• JSON encoded POST, PUT & PATCH bodies
• Pagination
• Auto loading related resource representations
• Overriding the HTTP method
• Rate limiting
• Authentication
• Caching
• Errors
• HTTP status codes
• In Summary