API Best Practices

API Best Practices

• 1.
  API Best Practices @urilavi http://bit.ly/scisr
• 2.
  Public API/ WebAPI HTTP / HTTPS XML/JSON
• 3.
  Rule #0 http://www.flickr.com/photos/holeymoon/2131118247/
• 4.
  Rule #1 -Funnel Try Build Adopt
• 5.
  Simplicity? TDD public API Atleast 3 clients Different languages http://www.flickr.com/photos/giosp/3933753363/
• 6.
  Cross Cutting Concerns Authentication/Authorization Versioning Sync/Async Re-entrance Pagination Caching Throttling
• 7.
  RESTfulness * Use plural names (reads better with GET) * Avoid methods (it isn’t traversal and grows fast) Nouns (Method-less) 2 base URLS per resource /events /events/10
• 8.
  RESTfulness HTTP Verbs oncollections/elements Create POST /events Fetch GET /events/12345 Update PUT /events/12345
• 9.
  Method-based * Use verbs * Make the documentation clear that these are “non resource” operations Convert Translate
• 10.
  Rule #2 -Relationships
• 11.
  Rule #2 -Relationships Keep it simple - 3 levels
• 12.
  Rule #2 -Relationships Keep it simple - 3 levels GET /lecturers/events/10
• 13.
  Rule #3 -Complexity? http://www.flickr.com/photos/takomabibelot/4373062612/
• 14.
  Rule #4 -Versioning * Maintain at least one version back GET api/v1/events/10
• 15.
  Rule #4 -Versioning * Maintain at least one version back GET api/v1/events/10
• 16.
  Rule #5 -Errors HTTP status codes {200, 400, 500} Verbose messages link to documentation
• 17.
  Rule #6 -Sync / Async Result available - sync Result available in x time - async PicScout’s API
• 18.
  Rule #7- Re-entrance http://www.flickr.com/photos/leovan/2152274834/ POST /funds/accounts/1000/ {‘value’: 100, ‘token’: ‘xbds213’}
• 19.
  Rule #8 -Formatting JaaD = JSON as a Default
• 20.
  Rule #9 -Automation? http://www.flickr.com/photos/r80o/39304743/ APIs are for humans