5. “IF SOFTWARE IS EATING THE WORLD,
APIS ARE EATING SOFTWARE.”
Steven Willmott CEO of 3Scale, during APIdays 2012 conference in San Francisco.
“SOFTWARE IS EATING THE WORLD”
Marc Andreessen in 2011.
8. The success of an API design
is measured by how quickly
developers can get up to start
using your API..
9. Characteristics of a Good API
Easy to learn
Easy to use, even without documentation
Well documented
Easy to extend
Appropriate to audience
Design Web APIs
13. Design Web APIs
GuruRS API
Mock Server
http://gururs.apiary-mock.com
$ curl http://gururs.apiary-mock.com/books
$ curl http://gururs.apiary-mock.com/books/2
$ curl http://gururs.apiary-mock.com/books/1/author
https://gist.github.com/taylorrf/b2a3e5ffcd49c1cf4c29
14. Keep URL Simple and Intuitive
/GetLastBook
Nouns are Good. Verbs are Bad.
/ListAllBooks
/SetBookStateTo
/ListAllAvaibleBooksOf
/Books
Design Web APIs
15. Use HTTP Verbs Properly
POST - Create a new resource.
PUT - Update a specific resource (by an identifier) or a collection of.
GET - Read a specific resource (by an identifier) or a collection of.
DELETE - Delete/remove a specific resource by an identifier
DELETE /books/:id
GET /books/:id/delete
Design Web APIs
16. Use HTTP Status Code Properly
Over 70 HTTP status code officially registered ( http://bit.ly/1qMa7aS )
200 - :ok - (Everthing worked)
400 - :bad_request - (The client did something wrong)
500 - :internal_server_error - (The API did something wrong)
201 :created
304 :not_modified
404 :not_found - The requested resource doesn't exist
401 : unauthorized - Not authenticated or allowed
Design Web APIs
17. Use HTTP Status Code Properly
CLI API
post /books [title: "book2"]
200 {error: “Author required"}
CLI API
post /books [title: "book2"]
400 {error: “Author required"}
Design Web APIs
18. Use HTTP Status Code Properly
CLI API
post /books [title: "book2"]
CLI API
post /books [title: "book2"]
400 {error: “You are not Admin"}
401 {error: “You are not Admin"}
Design Web APIs
400 :bad_request
401 : unauthorized
19. Filtering your Data
Design Web APIs
Pagination
offset - Initial point to consider
limit/length - number of elements you need
orderby - attribute to sort on
sort - ASC/DESC
Allow your users API to get only some parts of resources
https://api.gururs.com/books/?limit=20&sort=DESC
Ordering
20. Filtering your Data
Design Web APIs
Provide only the fields your client need
https://api.gururs.com/books/?limit=20&sort=DESC&fields=title,url
Filtering
Searching
https://api.gururs.com/books/?q=Design API
https://api.gururs.com/books/?type=ebook
21. Filtering your Data
Design Web APIs
Aliases for common queries
https://api.gururs.com/books/used
https://api.gururs.com/books/free_ebooks
https://api.gururs.com/books/deals
22. JSON format
Follow some JSON format convention for your great good.
Design Web APIs
http://jsonapi.org/ (Steve Klabnik & Yehuda Katz)
A standard for building APIs in JSON.
!
If you've ever argued with your team about the way your JSON responses should
be formatted, JSON API is your anti-bikeshedding weapon.
23. JSON format
http://jsonapi.org/
Design Web APIs
{
"links": {
"books.author": {
"href": "http://api.gururs.com/users/{books.author}",
"type": "users"
}
},
"books": [{
"id": "2",
"title": "Your API is Bad",
"links": {
"author": "1"
}
}]
}
24. Authentications
Design Web APIs
A RESTful API should be stateless.
Each request should come with some authentication credentials.
Basic HTTP Authentication over SSL
SSL everywhere. Always use SSL. No exceptions.
http://ssl.comodo.com/
25. Authentications
Design Web APIs
$ curl -IH "Authorization: Token token=16d7d60"
http://api.gururs.com/books
Easily expire or regenerate tokens without affecting the user’s password.
Greater control for each token, different access rules can be implemented.
Multiple tokens for each user to grant access to different API clients.
Token Based Authentication
26. Errors
Design Web APIs
{
"error" : “Something wrong.. sorry. try again.”,
}
{
"code" : 576,
"message" : "Something bad happened here..”,
"description" : "More details about the error here”
"url" :“http://api.gururs.com/docs/errors#576“
}
27. Errors
Design Web APIs
{
"code" : "validation_failed",
"message" : "Validation failed because you are stupid",
"errors" : [
{
"code" : "blank_field",
"field" : "title",
"message" : "Title cannot be blank"
},
{
"code" : "blank_field",
"field" : "author",
"message" : "Author cannot be blank"
}
]
}
29. Versioning
Design Web APIs
https://api.gururs.com/v2/books
URL Versioning
https://api.gururs.com/books
Custom request reader
api-version: 2
http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
https://api.gururs.com/books
Content type
Accept: application/vnd.gururs.v3+json
30. Wrapping Up
• Design First
• Keep URL Simple
• Use HTTP Verbs Properly
• Use HTTP Status Code Properly
• Allow your users to filter your data
• Follow some JSON format convention
!
• Authentication
!
• Errors
!
• Versioning
!
31. References
Surviving API’s with Rails - CodeSchool
https://www.codeschool.com/courses/surviving-apis-with-rails
!
Code Samples on Rails 4
https://github.com/codeschool/SurvivingAPIsDemoApp
Your API is Bad
https://leanpub.com/yourapiisbad
HTTP Succinctly
https://www.syncfusion.com/resources/techportal/ebooks/http
Web API Design: Crafting Interfaces that Developers Love
https://pages.apigee.com/web-api-design-ebook.html
32. References
Build the API First
http://confreaks.com/videos/3362-railsconf-build-the-api-first
"JSON API: convention driven API design", by Steve Klabnik APIdays Paris 2013
https://www.youtube.com/watch?v=FpS_E90-6O8
API Days Conference - YT Channel
https://www.youtube.com/user/apidays/videos
Traffic and Weather Podcast
http://trafficandweather.io/
