Procore's API: The Next Generation

Talk given at RailsConf 2017

Transcript

1. rails apis the next generation
2. derek carter
3. procore • 22 squads, ~120 engineers • > 10 year old app • > 40 distinct tools • > 500 controllers
4. überlith
6. autonomy
7. guild squad model squad product manager ux designer qa engineer engineer engineer squad product manager ux designer qa engineer engineer engineer squad product manager ux designer qa engineer engineer engineer tribe
10. why invest in an api?
11. internal benefits natural separation of concerns
12. internal benefits cleaner architecture
13. internal benefits change tolerance
14. external benefits customer trust
15. external benefits greatly expand your capabilities
16. external benefits become the ecosystem
17. what makes a good api?
18. a good api is: predictable & consistent static simple and clear flexible
19. how did we do it?
20. –jeff bezos “disagree and commit”
21. squad model squad product manager ux designer qa engineer engineer engineer squad product manager ux designer qa engineer engineer engineer squad product manager ux designer qa engineer engineer engineer tribe guide squad varies as needed
22. don’t make them think
23. have a style guide
25. boilerplate & examples
27. make a contract
28. items_index.json GET “lists/19/items” [ { "id": 23, "completed": false, "due_date": "2017-04-27", "list_id": 19, "text": "Bread", "visible": true }, { "id": 24, "completed": false, "due_date": "2017-04-27", "list_id": 19, "text": "Milk", "visible": true } ]
29. building static apis flexibly
30. use reusable components
31. class Api::V1::ItemsController < Api::V1::ApplicationController def index @items = Items.where(list_id: params[:list_id]) render json: @items end end
32. class Api::V1::ItemsController < Api::V1::ApplicationController def index completed_filter = params.dig(:filters, :completed) if completed_filter completed_bool = (completed_filter == true || completed_filter =~ (/true|t|yes|y|1/) || false ) @items = Item. where(list_id: params[:list_id], completed: completed_bool) else @items = Item.where(list_id: params[:list_id]) end render json: @items end end
33. class Api::V1::ItemsController < Api::V1::ApplicationController include Filterable filter_on :completed, type: :boolean def index @items = Item.where(list_id: params[:list_id]) render json: filtrate(@items) end end
34. class Api::V1::ItemsController < Api::V1::ApplicationController include Filterable filter_on :completed, type: :boolean sort_on :due_date, type: :datetime def index @items = Item.where(list_id: params[:list_id]) render json: filtrate(@items) end end
35. class Api::V1::ItemsController < Api::V1::ApplicationController include Filterable filter_on :completed, type: :boolean filter_on :query, type: :scope, internal_name: :search sort_on :due_date, type: :datetime def index @items = Item.where(list_id: params[:list_id]) render json: filtrate(@items) end end
36. serialization
37. gem 'active_model_serializers'
38. class ItemSerializer < ActiveModel::Serializer attributes :id, :completed, :created_at, :due_date, :note, :text, :visible belongs_to :list end
39. [ { "id": 1, "completed": false, "created_at": "2017-04-25T00:52:31.696Z", "due_date": "2017-04-27T00:00:00.000Z", "note": "Free range only", "text": "Eggs", "visible": true, "list": { "id": 1, "name": "Grocery", "description": "Weekly grocery list", "created_at": "2017-04-25T00:52:02.913Z", "updated_at": "2017-04-25T00:52:02.913Z" } } ]
40. class Api::V1::ItemsController < Api::V1::ApplicationController include Filterable filter_on :completed, type: :boolean def index @items = Item.includes(:list).where(list_id: params[:list_id]) render json: filtrate(@items) end def show @item = Item.includes(:list).find(params[:id]) render json: @item end end
41. class Api::V1::ItemsController < Api::V1::ApplicationController include Filterable filter_on :completed, type: :boolean def index @items = Item.includes(:list).where(list_id: params[:list_id]) render json: filtrate(@items), fields: [:id, :text], include: [] end def show @item = Item.includes(:list).find(params[:id]) render json: @item end end
42. class ApplicationSerializer < ActiveModel::Serializer
43. class ItemSerializer < ApplicationSerializer attributes :id, :completed, :text include_in [:normal, :extended] do attributes :completed, :created_at, :due_date, :note end include_in [:extended] do belongs_to :list end end
44. class Api::V1::ItemsController < Api::V1::ApplicationController include Filterable filter_on :completed, type: :boolean def index @items = Item.includes(:list).where(list_id: params[:list_id]) render json: filtrate(@items) end def show @item = Item.includes(:list).find(params[:id]) render json: @item, serializer_view: :extended end end
45. [ { "id": 1, "completed": false, "text": "Eggs" } ] { "id": 1, "completed": false, "text": "Eggs", "created_at": "2017-04-25T00:52:31.696Z", "due_date": "2017-04-27T00:00:00.000Z", "note": "Free range only", "list": { "id": 1, "name": "Grocery", "description": "Weekly grocery list", "created_at": "2017-04-25T00:52:02.913Z", "updated_at": "2017-04-25T00:52:02.913Z" } } #show #index
46. documenting the api
47. an undocumented api is a worthless api
48. wikis & *.md
51. swagger (aka openapi specification)
52. –swagger’s website “swagger is a project used to describe and document restful apis”
53. { "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "license": { "name": "MIT" } }, "host": "petstore.swagger.io", "basePath": "/v1", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "summary": "List all pets", "operationId": "listPets", "tags": [ "pets" ], "parameters": [ { "name": "limit",
54. benefits of swagger/openapi guided structure
55. benefits of swagger/openapi style and content are separated
56. benefits of swagger/openapi machine readable
57. detriments of swagger another thing to learn
58. writing swagger at procore
59. procore’s swagger file 7.7mb json file
62. • don’t make them think • build a style guide • disagree and commit • make contracts first • use resusable components • document your damn API
63. derek carter procore.com/jobs