Build the API First (Rosie Hoyem and Sonja Hall)

Presented at RailsConf 2014.

The next five years of web development are all about data applications and APIs. Learn why it is useful to leverage Rails-API to build them. This modular subset of a normal Rails application streamlines the process of building a standardized API that can easily be consumed by a wide-array of applications. We’ll explore the approach of 'building the API first' and demonstrate the expanding utility of the Rails-API framework as user interfaces extend beyond HTML into native applications and APIs.

Transcript

1. BUILD THE FIRST Sonja Hall @sonjahall Washington, DC Web Design Engineer, Venga Rosie Hoyem @rhoyem Minneapolis, MN Developer, Minnesota Population Center
2. OVERVIEW nigesecurityguy.wordpress.com Intro: Patterns that Support Good Design 1. Why Build the API First 2. API Best Practices 3. Why Use Rails to Build an API
3. APIs & ARCHITECTURE
4. PATTERNS: OUR GUIDE FOR ORGANIZING CITIES
6. PATTERNS: OUR GUIDE FOR WRITING GOOD OO SOFTWARE
8. CONVENTION OVER CONFIGURATION
9. WHY BUILD THE API FIRST
13. nextcity.org
14. A CONSISTENT API SHOULD BE THE INFRASTRUCTURE SUPPORTING YOUR APP
15. ONE API, MULTIPLE CLIENTS developer-agent.com
16. www.target360.com REST SERVER + MOBILE APPLICATION Minimal duplication across platforms. Use the same API for mobile applications.
17. REST SERVER + JAVASCRIPT FRAMEWORK Use the same API to send data to a Javascript client.
18. WITHOUT A GOOD STANDARDIZED SERVER SOLUTION, YOU CAN’T HAVE STANDARDIZED CLIENT CODE.
19. WHY BUILD THE API FIRST? 1. Your application can easily pass around data. 2. Minimal duplication across platforms. 3. Standardized server code promotes standardized client code.
20. API BEST PRACTICES decorately.com
21. WHY IS A WELL-DESIGNED API SO IMPORTANT?
22. A WELL-DESIGNED API IS AMONG A COMPANY’S GREATEST ASSETS
23. A POORLY-DESIGNED API CAN BE A HUGE LIABILITY
24. DESIGN AN API FOR EXPERIENCE, NOT DATA
25. CONSISTENCY CONSISTENCY CONSISTENCY
26. (THE ALTERNATIVE)
27. DOCUMENT DOCUMENT DOCUMENT
28. CAN’T STAND DOCUMENTING? TRY DOCUMENTATION DRIVEN DEVELOPMENT * see APIARY.IO
29. * APIARY.IO EXAMPLE
30. THE LIFE SPAN OF AN API Version your APIs (and plan for deprecation from version ONE)
31. GIVE YOUR API A FOREVER HOME
32. JSON STANDARDS: jsonapi.org “By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application.” - STEVE KLABNIK
33. EXAMPLE JSON from jsonapi.org
34. TOOLS FOR A SHARED SOLUTION
35. TOOLS SINATRA RAILS-API RAILS ONE OF 14 OPTIONS ON RUBY TOOLBOX HAND ROLLING YOUR OWN VS VS VS WITH
36. STOP THE COGNITIVE DEPLETION!
37. SURE THIS WORKS, BUT…
38. gem 'rails-api' gem 'active_model_serializers'
39. RAILS-API COMES WITH BAKED-IN SOLUTIONS FOR AN ARRAY OF POORLY UNDERSTOOD PROBLEMS
40. HANDLED AT THE MIDDLEWARE LAYER: Security: Rails detects and thwarts IP spoofing attacks and handles cryptographic signatures in a timing attack aware way.
41. STOP THE COGNITIVE DEPLETION!
42. SERIALIZERS replace hash-driven development with object-oriented development.
43. # app/serializers/users class UserSerializer < ActiveModel::Serializer attributes :id, :username, :email, :url has_many :list_items def url user_url(object) end end SERIALIZERS
44. { user: { id: 1, username: "TestUserOne!", email: "test2@email.com", url: "http://localhost:3000/users/1", list_items: [ { id: 1, content: "Learn to Code", user_id: 1 }, { id: 2, content: "Build a house", user_id: 1 } ] } } GET /users/1
45. IN CONCLUSION
46. SHARED SOLUTION AREA OF EXPERIMENTATION API DESIGN
47. ANY CONVENTION IS BETTER THAN NO CONVENTION.
48. SHARING IS CARING
49. IT SEEMED LIKE A GOOD IDEA AT THE TIME...
50. NOBODY WANTS THEIR PROJECTS TO END UP LIKE THIS
51. MOST BUGS CAN BE FIXED WITH REALLY GOOD DOCUMENTATION.
52. THANKS! @rhoyem @sonjahall
53. This is a fundamental view of the world. It says that when you build a thing you cannot merely build that thing in isolation, but must repair the world around it, and within it, so that the larger world at that one place becomes more coherent, and more whole; and the thing which you make takes its place in the web of nature, as you make it. ~ Christopher Alexander
54. RESOURCES: Code & Tools BUCKETLIZTR API: https://github.com/rosiehoyem/rails-api-bucketliztr RAILS-API: https://github.com/rails-api/rails-api ACTIVE MODELSERIALIZERS: https://github.com/rails- api/active_model_serializers APIARY: http://apiary.io/ FDOC: https://github.com/square/fdoc RUBY TOOLBOX, API BUILDERS:: https://www.ruby-toolbox. com/categories/API_Builders
55. RESOURCES: Railscasts Rails-api: http://railscasts.com/episodes/348-the-rails-api-gem ActiveModel::Serializers: http://railscasts.com/episodes/409-active-model- serializers Rails API versioning: http://railscasts.com/episodes/350-rest-api-versioning Middleware: http://railscasts.com/episodes/319-rails-middleware-walkthrough
56. RESOURCES: Blog Posts Investigating API Developer Tools: http://mayerdan. com/programming/2014/01/29/investigating-api-tooling/ API Design for Humans: http://signalvnoise.com/posts/3018-api-design-for- humans
57. RESOURCES: Standards JSONAPI: http://jsonapi.org/ JSON-Schema: http://json-schema.org/implementations.html JSON-LD: http://www.w3.org/TR/json-ld-syntax/ Schema.org: http://schema.org/
58. RESOURCES: RailsConf Talks Yahuda Katz, Rails: The Next Five Years:: http://www.confreaks. com/videos/907-railsconf2012-rails-the-next-five-years Noel Rapin, Rails vs. the Client Side: http://www.confreaks. com/videos/2447-railsconf2013-rails-vs-the-client-side