Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Design Web Api

1,359 views

Published on

Published in: Technology, Design
  • Be the first to comment

  • Be the first to like this

Design Web Api

  1. 1. Design Web APIs Tailor Fontela An brief introduction to start crafting API
  2. 2. @tailorfontela
  3. 3. mytraining.pro
  4. 4. Motivations Multiple Clients Browsers, Iphone and Android Apps, etc.. JavaScript Libraries Angular, Ember, Backbone, Knockout Startups and Business Core, Social Data, Marketing
  5. 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.
  6. 6. API Application Programming Interface
  7. 7. REST Representational State Transfer
  8. 8. The success of an API design is measured by how quickly developers can get up to start using your API..
  9. 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
  10. 10. Imagine how developers will use your API
  11. 11. Fail FastMock Share Design First Design Web APIs
  12. 12. Design Web APIs apiary.io Collaborative design, instant API mock, generated documentation..
  13. 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. 14. Keep URL Simple and Intuitive /GetLastBook Nouns are Good. Verbs are Bad. /ListAllBooks /SetBookStateTo /ListAllAvaibleBooksOf /Books Design Web APIs
  15. 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/:idGET /books/:id/delete Design Web APIs
  16. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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" } ] }
  28. 28. Errors Design Web APIs
  29. 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. 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. 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. 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/
  33. 33. Thanks! @tailorfontela me@taylorrf.com Questions?

×