Slide 1
Slide 1 text
11 Tips for better APIs
@FanieReynders
Team Lead – EOH Microsoft Services
Slide 2
Slide 2 text
“
”
An application programming interface a
protocol intended to be used as an
interface by software components to
communicate with each other.
- Wikipedia
Slide 3
Slide 3 text
API Design
Start from “outside-in”
“What are we trying to achieve?”
Developer as the user
Design communicates usage
Use best practice guidelines
Slide 4
Slide 4 text
“
”
Affordance is a design property that
communicates how something should be
used without requiring documentation.
conflict between design affordance
and documentation
Slide 5
Slide 5 text
Use nouns, not verbs
Keep things simple
Simple & intuitive base URLs
No verbs in base URLs
2 base URLs per resource
Collection - /cars
Single element - /cars/31
Slide 6
Slide 6 text
Use verbs for operations
POST, GET, PUT, DELETE
CRUD
Resource POST GET PUT DELETE
/cars Create a new
car
List cars Bulk update
cars
Delete all cars
/cars/2615 Error Show car 2615 Update car
2615, if not
exist, error
Delete car
2615
Slide 7
Slide 7 text
Be consistent
Allows developers to predict
Avoid mixes of plural & singular
Concrete names are better than abstractions
Slide 8
Slide 8 text
Simplify associations
Limit routes to /resource/identifier/resource
Sweep complexity under the ‘?’
/cars/2615/drivers?from=jhb&since=2004
rather than
/cars/2615/drivers/jhb/2004
Slide 9
Slide 9 text
Error handling
Standard HTTP codes – use them
Everything worked – success (200 OK)
The application did something wrong – client error (400 Bad Request)
The API did something wrong – server error (500 Internal Server Error)
Slide 10
Slide 10 text
Error handling
Include user-friendly messages
Link to more info
401 – Unauthorized
{
Message: “The API key provided is not valid”,
ErrorId: 273343,
MoreInfo: “http://dev.someapi.net/errors/273343
}
Slide 11
Slide 11 text
Versioning
Never release without
Must be highest scope
Use simple ordinal numbers
v1 not v1.2
Slide 12
Slide 12 text
Partial responses
Scoped response
/cars?fields=id,name
Use limits & offsets with defaults
Provide meta-data
Support multiple formats
JSON (default)
XML
Atom
Slide 13
Slide 13 text
Non-resource responses
Use verbs, not nouns
Calculate
Convert
Project
Slide 14
Slide 14 text
What about Search?
Scoped search
/cars/2231/drivers?q=Fanie
Global search
/search?q=Fanie
Slide 15
Slide 15 text
Authentication
NEVER send passwords through the wire
Use SSL
OAuth
Slide 16
Slide 16 text
Consolidate
Cleaner & easier
Keep API separate from documentation
http://api.somesite.net
http://developers.somesite.net
Provide SDK
Slide 17
Slide 17 text
That’s all folks!