Saturday, June 27, 2015

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
Post a Comment