API Best Practices
@urilavi
http://bit.ly/scisr

Public API/ Web API
HTTP / HTTPS
XML/JSON

Rule #0
http://www.flickr.com/photos/holeymoon/2131118247/

Rule #1 - Funnel
Try
Build
Adopt

Simplicity?
TDD public API
At least 3 clients
Different languages
http://www.flickr.com/photos/giosp/3933753363/

Cross Cutting Concerns
Authentication/Authorization
Versioning
Sync/Async
Re-entrance
Pagination
Caching
Throttling

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

RESTfulness
HTTP Verbs on collections/elements
Create
POST /events
Fetch
GET /events/12345
Update
PUT /events/12345

Method-based
* Use verbs
* Make the
documentation clear
that these are “non
resource” operations
Convert
Translate

Rule #2 - Relationships

Rule #2 - Relationships
Keep it simple - 3 levels

Rule #2 - Relationships
Keep it simple - 3 levels
GET /lecturers/events/10

Rule #3 - Complexity?
http://www.flickr.com/photos/takomabibelot/4373062612/

Rule #4 - Versioning
* Maintain at least one
version back
GET api/v1/events/10

Rule #4 - Versioning
* Maintain at least one
version back
GET api/v1/events/10

Rule #5 - Errors
HTTP status codes
{200, 400, 500}
Verbose messages
link to documentation

Rule #6 - Sync / Async
Result available - sync
Result available in x time - async
PicScout’s API

Rule #7- Re-entrance
http://www.flickr.com/photos/leovan/2152274834/
POST /funds/accounts/1000/
{‘value’: 100, ‘token’: ‘xbds213’}

Rule #8 - Formatting
JaaD = JSON as a Default

Rule #9 - Automation?
http://www.flickr.com/photos/r80o/39304743/
APIs are for humans