Make Hypermedia APIs in Ruby

This presentation is an introduction of Hypermedia and how to make Hypermedia APIs in Ruby with tools like ActiveModel::Serializers or ROAR.

Transcript

1. Make Hypermedia APIs in Ruby
2. Nicolas Mérouze Futurist engineer @nmerouze http://merouze.me
3. RESTful web APIs
4. URIs (e.g. /posts, /posts/42)
5. URIs (e.g. /posts, /posts/42) Media types (e.g. application/json, text/html)
6. URIs (e.g. /posts, /posts/42) Media types (e.g. application/json, text/html) Request and response codes (e.g. 200, 302, 404)
7. URIs (e.g. /posts, /posts/42) Media types (e.g. application/json, text/html) Request and response codes (e.g. 200, 302, 404) Requests methods (e.g. GET, POST, PATCH, DELETE)
8. What is exactly REST?
9. Identification of resources
10. Identification of resources Manipulation of resources through these representations
11. Identification of resources Manipulation of resources through these representations Self-descriptive messages
12. Identification of resources Manipulation of resources through these representations Self-descriptive messages Hypermedia as the engine of application state (aka HATEOAS)
13. HATEOAS “A client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.” – Wikipedia
14. REST == Hypermedia
15. Example
22. Semantic
23. HTML is semantic
24. JSON and XML are not
25. Media types to the rescue!
26. HAL http://stateless.co/hal_specification.html
27. HAL http://stateless.co/hal_specification.html Collection+JSON http://amundsen.com/media-types/collection/
28. HAL http://stateless.co/hal_specification.html Collection+JSON http://amundsen.com/media-types/collection/ Siren https://github.com/kevinswiber/siren
29. HAL http://stateless.co/hal_specification.html Collection+JSON http://amundsen.com/media-types/collection/ Siren https://github.com/kevinswiber/siren JSON API http://jsonapi.org
30. Maker’s time!
31. Models
32. class AdminUser < ActiveRecord::Base end class Post < ActiveRecord::Base belongs_to :admin_user end
33. Rails
34. class PostsController < ApplicationController def index @posts = Post.all render :json => @posts end end
35. [ { "admin_user_id": 1, "id": 1, "title": "Welcome to Hyper" } ]
36. Rails + ActiveModel::Serializers
37. gem "active_model_serializers", "~> 0.7.0"
38. class PostSerializer < ActiveModel::Serializer attributes :id, :title end
39. { "posts": [ { "id": 1, "title": "Welcome to Hyper" } ] }
40. class AdminUserSerializer < ActiveModel::Serializer attributes :id, :email end class PostSerializer < ActiveModel::Serializer attributes :id, :title has_one :admin_user end
41. { "posts": [ { "admin_user": { "email": "admin@example.com", "id": 1 }, "id": 1, "title": "Welcome to Hyper" } ] }
42. class PostSerializer < ActiveModel::Serializer embed :ids, :include => true attributes :id, :title has_one :admin_user end
43. { "admin_users": [ { "email": "admin@example.com", "id": 1 } ], "posts": [ { "admin_user_id": 1, "id": 1, "title": "Welcome to Hyper" } ] }
44. Rails + ROAR
45. gem "roar-rails"
46. class PostsController < ApplicationController include Roar::Rails::ControllerAdditions respond_to :json def index posts = Post.all respond_with posts, :represent_items_with => PostRepresenter end end
47. # app/representers/post_representer.rb class PostRepresenter < Roar::Decorator include Roar::Representer::JSON property :id property :title end
48. { "posts": [ { "id": 1, "title": "Welcome to Hyper" } ] }
49. # In config/environments config.representer.default_url_opt ions = {:host => "hyper.com"}
50. class PostRepresenter < Roar::Decorator include Roar::Representer::JSON include Roar::Representer::Feature::Hypermedia property :id property :title link :self do post_url(represented) end end
51. { "posts": [ { "id": 1, "links": [ { "href": "http://hyper.com/posts/1", "rel": "self" } ], "title": "Welcome to Hyper" } ] }
52. class PostRepresenter < Roar::Decorator include Roar::Representer::JSON::HAL property :id property :title link :self do post_url(represented) end end
53. { "posts": [ { "_links": { "self": { "href": "http://hyper.com/posts/1" } }, "id": 1, "title": "Welcome to Hyper" } ] }
54. Grape
55. Hypa
56. Blog.collection :posts do |c| c.href '/posts' c.methods get: :self, post: :create c.resource do |r| r.href '/posts/{id}' r.methods get: :self, patch: :update, delete: :destroy r.integer :id r.string :title end c.action :self do |a| a.integer :limit a.array :title_in end c.action :create do |a| a.string :title, required: true end end
57. GET /posts { "posts": [{ "id": 42, "title": "Hyper Welcome!" }, { "id": 43, "title": "Hyper Goodbye!" }], "meta": { "actions": [ { "rel": "self", "method": "get", "href": "/posts", "params": [{"name": "limit", "type": "integer"}] }, { "rel": "create", "method": "post", "href": "/posts", "params": [{"name": "title", "type": "string", "required": true}] } ] } }
58. GET /posts/42 { "posts": [{ "id": 42, "title": "Hyper Welcome!" }], "meta": { "actions": [ { "rel": "self", "method": "get", "href": "/posts/42" }, { "rel": "update", "method": "patch", "href": "/posts/42" }, { "rel": "destroy", "method": "delete", "href": "/posts/42" } ] } }
59. Links
60. https://github.com/newhavenrb/conferences/wiki/Designing-Hypermedia-APIs http://37signals.com/svn/posts/3373-getting-hyper-about-hypermedia-apis https://github.com/rails-api/active_model_serializers https://github.com/intridea/grape https://github.com/apotonick/roar https://github.com/nmerouze/hypa
61. Thank you!
62. Nicolas Mérouze Contact me if you need to make a good API @nmerouze http://speakerdeck.com/nmerouze http://merouze.me