design web api
DESCRIPTION
TRANSCRIPT
Design Web APIs
Tailor Fontela
An brief introduction to start crafting API
@tailorfontela
mytraining.pro
MotivationsMultiple Clients Browsers, Iphone and Android Apps, etc..
JavaScript Libraries Angular, Ember, Backbone, Knockout
Startups and Business Core, Social Data, Marketing
“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.
APIApplication Programming Interface
RESTRepresentational State Transfer
The success of an API design is measured by how quickly developers can get up to start using your API..
Characteristics of a Good APIEasy to learn
Easy to use, even without documentation
Well documented
Easy to extend
Appropriate to audience
Design Web APIs
Imagine how developers will use your API
Fail FastMock Share
Design First
Design Web APIs
Design Web APIs
apiary.ioCollaborative design, instant API mock, generated documentation..
Design Web APIs
GuruRS APIMock 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
Keep URL Simple and Intuitive
/GetLastBook
Nouns are Good. Verbs are Bad.
/ListAllBooks
/SetBookStateTo
/ListAllAvaibleBooksOf
/Books
Design Web APIs
Use HTTP Verbs ProperlyPOST - 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/:idGET /books/:id/delete
Design Web APIs
Use HTTP Status Code ProperlyOver 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 :created304 :not_modified404 :not_found - The requested resource doesn't exist401 : unauthorized - Not authenticated or allowed
Design Web APIs
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
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
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
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
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
JSON formatFollow 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.
JSON formathttp://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" } }]}
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/
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
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“ }
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" } ]}
Errors
Design Web APIs
Versioning
Design Web APIs
https://api.gururs.com/v2/booksURL 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
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!
References
Surviving API’s with Rails - CodeSchoolhttps://www.codeschool.com/courses/surviving-apis-with-rails!Code Samples on Rails 4https://github.com/codeschool/SurvivingAPIsDemoApp
Your API is Bad https://leanpub.com/yourapiisbad
HTTP Succinctlyhttps://www.syncfusion.com/resources/techportal/ebooks/http
Web API Design: Crafting Interfaces that Developers Love https://pages.apigee.com/web-api-design-ebook.html
References
Build the API Firsthttp://confreaks.com/videos/3362-railsconf-build-the-api-first
"JSON API: convention driven API design", by Steve Klabnik APIdays Paris 2013https://www.youtube.com/watch?v=FpS_E90-6O8
API Days Conference - YT Channelhttps://www.youtube.com/user/apidays/videos
Traffic and Weather Podcasthttp://trafficandweather.io/
