Practical Web APIs, rails' style

a general talk of the basic components and properties of building good APIs in rails

presented in http://www.meetup.com/Ruby-Meetup-Oslo/events/225349680/

the text version of this slides can be found in
https://gist.github.com/fespinoza/b3e80cb93b6491865bd4

Transcript

1. Practical Web APIs, rails’ style by Felipe Espinoza
2. fespinoza fespinozacast
4. What is an API?
5. Application programming interface https://en.wikipedia.org/wiki/Application_programming_interface An API expresses a software component in terms of its operations, inputs, outputs, and underlying types. An API defines functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising the interface
6. My Definition Endpoint: a single IN/Out operation Web API: an API is a set of Endopints that establish a contract of the way Clients can communicate with the system exposing the API
7. Properties of good APIs consistent “self-documented” stable friendly regarding breaking changes interoperable secure useful :)
8. APIs in Rails HTTP 1.1 JSON Rails conventions REST* * Rails itself is not really restful, it lacks hateoas
9. Endpoint Structure
10. Request Response • HTTP verb • URL • Headers • Body/Parameters • Status Code • Headers • Body Endpoint Structure
15. https://gist.github.com/fespinoza/440b250d19a0e9979909
16. Basic Concerns About Endpoints
17. Authentication • HTTP Auth: when i don’t need to know who is logging in • Token Based Auth: when i want to identify the user and authenticate him • Authorization header • JWT tokens FTW! http://jwt.io Secure
18. Error normalization { "error": { "status": 422, "id": "unprocessable_entity", "message": "The given params are not valid", "documentation_url": "https://api.com/docs", "validations": { "title": [ "can't be blank" ] } } } Consistent
19. Endpoint design 1. Create a proposal in markdown 2. Make a PR out of it 3. Discuss and finally agree 4. Mock it! 5. Profit Useful :)
20. 1. Create a proposal in markdown Useful :)
21. 2. Discussions 2. Make a PR out of it Useful :)
22. 3. Agree 3. Discuss and finally agree Useful :)
23. 4. Mock it 4. Mock it! Useful :)
24. 5. Profit! Useful :)
25. Useful HTTP headers Request Response ◦ Content-Type ◦ Accept ◦ Accept-Language ◦ Authorization ◦ If-None-Match ◦ User-Agent ◦ ETag ◦ Content-Type Interoperable
26. HTTP status codes
27. Interoperable
28. HTTP status codes Range Meaning 2XX Success 3XX Redirection 4XX Client error 5XX Server error Interoperable
29. Design Guidelines https://github.com/interagent/http-api-design https://github.com/hyperoslo/api-playbook Consistent
30. Oops* *let’s avoid the extra O with proper ops • logging • error tracking • uptime checking • performance monitoring • event tracking => Papertrail => Sentry/App Signal => Nagios => New relic, App Signal, Skylight => Mix pannel Stable
31. Rails Gems
32. Authentication gem 'devise' gem 'doorkeeper' gem 'doorkeeper-jwt' gem 'cancancan' https://github.com/doorkeeper-gem/doorkeeper https://github.com/chriswarren/doorkeeper-jwt Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwib… Secure
33. Versioning gem 'api-versions' • version: • routes • controllers • views • a new version of the enpoint, defaults to the previous version Accept: application/json, application/vnd.myshop+json; version=2 Change Friendly https://github.com/EDMC/api-versions
34. Testing & Documentation gem 'rspec_api_documentation' gem 'apitome' https://github.com/zipmark/rspec_api_documentation https://github.com/modeset/apitome https://github.com/Apipie/apipie-rails self-documented • Other Alternative
37. Paw https://luckymarmot.com/paw
38. https://speakerdeck.com/fespinoza/practical-web-apis-rails-style
39. Thanks! fespinoza fespinozacast