JSON API in the Ruby world

Slides from my first talk ever, given at the first edition of BalkanRuby conference in Sofia, Bulgaria will give answers to questions like such: What is json:api? What gems could you use in your Rails API in order to meet the json:api specification? What are the pros and cons of Active Model Serializers (AMS) and Fast JSON API gems?

Transcript

1. JSON API in the Ruby world Gabriela Luhova
9. JSON API specification
11. Overview
12. Content-Type: application/vnd.api+json
13. GET /articles HTTP/1.1 Accept: application/vnd.api+json
14. { "type": "articles", "id": "1", "attributes": { "title": "Rails is Omakase" }, "relationships": { "author": { "links": { "self": "/articles/1/relationships/author", "related": "/articles/1/author" }, "data": { "type": "people", "id": "9" } } } }
15. Benefits
16. Compound Documents
17. GET https://api.example.com/posts?include=author
18. { "data": [{ "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" }, "links": { "self": "http://example.com/articles/1" }, "relationships": { "author": { "links": { "self": "http://example.com/articles/1/relationships/author", "related": "http://example.com/articles/1/author" }, "data": { "type": "people", "id": "9" } } } }], "included": [{ "type": "people", "id": "9", "attributes": { "first-name": "Dan", "last-name": "Gebhardt", "twitter": "dgeb" }, "links": { "self": "http://example.com/people/9" } }] }
20. Sparse Fieldsets
21. GET /articles?include=author&;fields[articles]=title,body&;fields[people]=name HTTP/1.1 Accept: application/vnd.api+json
22. Caching
23. Summary
24. • API response design convention • Compound Documents • Sparse Fields • Caching
25. Active Model Serializers
26. gem 'active_model_serializers', '0.10.0.rc4'
27. Configuration
28. # config/initializers/active_model_serializers.rb require 'active_model_serializers' ActiveModelSerializers.config.adapter = :json_api
29. Usage
30. • You have a resource which is an ActiveRecord/ActiveModel object. • You create the ActiveModel::Serializer for it. • Every time you render it as JSON, the serializer will be used.
31. Example
32. Customer Order WarrantyPolicy has_many has_many
33. class CustomerSerializer < ActiveModel::Serializer attributes :email, :name, :phone has_many :orders end
34. class OrderSerializer < ActiveModel::Serializer attributes :payment_type, :status, :shipping_address has_many :warranty_policies end
35. class WarrantyPolicySerializer < ActiveModel::Serializer attributes :model_type_serialized, :serial_number, :period def model_type_serialized object.model_type.constantize.human_name end end
36. @customer = current_customer render json: @customer, include: ['orders', 'orders.warranty_policies']
37. {"data":{"id":"1", "type":"customers", "attributes":{"email":"test@test.com"}, "relationships":{"orders":{"data":[{"id":"1","type":"orders"}]}}}, "included":[{"id":"1", "type":"orders", "attributes":{"payment-type":"cash", "status":"finished", "shipping-address":"from the seller's office"}, "relationships":{"warranty-policies": {"data":[{"id":"1", "type ":"warranty-policies"}]}}}, {"id":"1", "type":"warranty-policies", "attributes":{"model-type-serialized":"Laptops", "serial-number":"H7N0CV09406574G", "period":24}}]}
38. @customer = current_customer render json: @customer, include: 'orders', fields: {orders: ['payment_type', 'status']}
39. Caching
42. # config/environments/development.rb config.cache_store = :mem_cache_store, "localhost" config.action_controller.perform_caching = true
43. class CustomerSerializer < ActiveModel::Serializer cache key: 'customer' attributes :id, :email, :name, :phone has_many :orders end
44. Summary
45. Fast JSON API
46. gem 'fast_jsonapi'
47. Usage
48. rails g serializer Customer name email phone
49. Example
50. Customer Order WarrantyPolicy has_many has_many
51. class CustomerSerializer include FastJsonapi::ObjectSerializer attributes :email, :name, :phone has_many :orders end
52. class OrderSerializer include FastJsonapi::ObjectSerializer attributes :id, :payment_type, :status, :shipping_address has_many :warranty_policies end
53. class WarrantyPolicySerializer include FastJsonapi::ObjectSerializer attributes :serial_number, :period attribute :model_type_serialized do |object| object.model_type.constantize.human_name end end
54. @customer = Customer.find params[:id] options = {} options[:include] = [:orders, :'orders.warranty_policies'] serialized_customer = CustomerSerializer.new(@customer, options) .serialized_json render json: serialized_customer
55. {"data":{"id":"1", "type":"customers", "attributes":{"email":"test@test.com"}, "relationships":{"orders":{"data":[{"id":"1","type":"orders"}]}}}, "included":[{"id":"1", "type":"orders", "attributes":{"payment-type":"cash", "status":"finished", "shipping-address":"from the seller's office"}, "relationships":{"warranty-policies": {"data":[{"id":"1", "type ":"warranty-policies"}]}}}, {"id":"1", "type":"warranty-policies", "attributes":{"model-type-serialized":"Laptops", "serial-number":"H7N0CV09406574G", "period":24}}]}
56. Caching
57. class CustomerSerializer include FastJsonapi::ObjectSerializer set_type :customer # optional cache_options enabled: true, cache_length: 12.hours attributes :id, :email, :name, :phone has_many :orders end
58. Speed comparison to AMS
61. AMS vs Fast JSON API
62. AMS • Support of multiple adapters • Compound documents • Sparse fields • Caching issues • Handles homogenous and not homogenous lists Fast JSON API • Only JSON API specification support • Compound documents • No sparse fields implementation • Better performance of collection serialization • Aimed at serialization of homogenous list of objects
63. Summary
64. THANK YOU!