active_model_serializers 0.8.3 → 0.10.8

Sign up to get free protection for your applications and to get access to all the features.
Files changed (235) hide show
  1. checksums.yaml +5 -5
  2. data/.github/ISSUE_TEMPLATE.md +29 -0
  3. data/.github/PULL_REQUEST_TEMPLATE.md +15 -0
  4. data/.gitignore +17 -0
  5. data/.rubocop.yml +105 -0
  6. data/.simplecov +110 -0
  7. data/.travis.yml +50 -24
  8. data/CHANGELOG.md +650 -6
  9. data/CODE_OF_CONDUCT.md +74 -0
  10. data/CONTRIBUTING.md +105 -0
  11. data/Gemfile +69 -1
  12. data/{MIT-LICENSE.txt → MIT-LICENSE} +3 -2
  13. data/README.md +195 -545
  14. data/Rakefile +64 -8
  15. data/active_model_serializers.gemspec +62 -23
  16. data/appveyor.yml +28 -0
  17. data/bin/bench +171 -0
  18. data/bin/bench_regression +316 -0
  19. data/bin/rubocop +38 -0
  20. data/bin/serve_benchmark +39 -0
  21. data/docs/README.md +41 -0
  22. data/docs/STYLE.md +58 -0
  23. data/docs/general/adapters.md +269 -0
  24. data/docs/general/caching.md +58 -0
  25. data/docs/general/configuration_options.md +185 -0
  26. data/docs/general/deserialization.md +100 -0
  27. data/docs/general/fields.md +31 -0
  28. data/docs/general/getting_started.md +133 -0
  29. data/docs/general/instrumentation.md +40 -0
  30. data/docs/general/key_transforms.md +40 -0
  31. data/docs/general/logging.md +21 -0
  32. data/docs/general/rendering.md +293 -0
  33. data/docs/general/serializers.md +495 -0
  34. data/docs/how-open-source-maintained.jpg +0 -0
  35. data/docs/howto/add_pagination_links.md +138 -0
  36. data/docs/howto/add_relationship_links.md +140 -0
  37. data/docs/howto/add_root_key.md +62 -0
  38. data/docs/howto/grape_integration.md +42 -0
  39. data/docs/howto/outside_controller_use.md +66 -0
  40. data/docs/howto/passing_arbitrary_options.md +27 -0
  41. data/docs/howto/serialize_poro.md +73 -0
  42. data/docs/howto/test.md +154 -0
  43. data/docs/howto/upgrade_from_0_8_to_0_10.md +265 -0
  44. data/docs/integrations/ember-and-json-api.md +147 -0
  45. data/docs/integrations/grape.md +19 -0
  46. data/docs/jsonapi/errors.md +56 -0
  47. data/docs/jsonapi/schema/schema.json +366 -0
  48. data/docs/jsonapi/schema.md +151 -0
  49. data/docs/rfcs/0000-namespace.md +106 -0
  50. data/docs/rfcs/template.md +15 -0
  51. data/lib/action_controller/serialization.rb +43 -38
  52. data/lib/active_model/serializable_resource.rb +11 -0
  53. data/lib/active_model/serializer/adapter/attributes.rb +15 -0
  54. data/lib/active_model/serializer/adapter/base.rb +18 -0
  55. data/lib/active_model/serializer/adapter/json.rb +15 -0
  56. data/lib/active_model/serializer/adapter/json_api.rb +15 -0
  57. data/lib/active_model/serializer/adapter/null.rb +15 -0
  58. data/lib/active_model/serializer/adapter.rb +24 -0
  59. data/lib/active_model/serializer/array_serializer.rb +12 -0
  60. data/lib/active_model/serializer/association.rb +71 -0
  61. data/lib/active_model/serializer/attribute.rb +25 -0
  62. data/lib/active_model/serializer/belongs_to_reflection.rb +11 -0
  63. data/lib/active_model/serializer/collection_serializer.rb +88 -0
  64. data/lib/active_model/serializer/concerns/caching.rb +300 -0
  65. data/lib/active_model/serializer/error_serializer.rb +14 -0
  66. data/lib/active_model/serializer/errors_serializer.rb +32 -0
  67. data/lib/active_model/serializer/field.rb +90 -0
  68. data/lib/active_model/serializer/fieldset.rb +31 -0
  69. data/lib/active_model/serializer/has_many_reflection.rb +10 -0
  70. data/lib/active_model/serializer/has_one_reflection.rb +7 -0
  71. data/lib/active_model/serializer/lazy_association.rb +96 -0
  72. data/lib/active_model/serializer/link.rb +21 -0
  73. data/lib/active_model/serializer/lint.rb +150 -0
  74. data/lib/active_model/serializer/null.rb +17 -0
  75. data/lib/active_model/serializer/reflection.rb +210 -0
  76. data/lib/active_model/{serializers → serializer}/version.rb +1 -1
  77. data/lib/active_model/serializer.rb +343 -442
  78. data/lib/active_model_serializers/adapter/attributes.rb +13 -0
  79. data/lib/active_model_serializers/adapter/base.rb +83 -0
  80. data/lib/active_model_serializers/adapter/json.rb +21 -0
  81. data/lib/active_model_serializers/adapter/json_api/deserialization.rb +213 -0
  82. data/lib/active_model_serializers/adapter/json_api/error.rb +96 -0
  83. data/lib/active_model_serializers/adapter/json_api/jsonapi.rb +49 -0
  84. data/lib/active_model_serializers/adapter/json_api/link.rb +83 -0
  85. data/lib/active_model_serializers/adapter/json_api/meta.rb +37 -0
  86. data/lib/active_model_serializers/adapter/json_api/pagination_links.rb +88 -0
  87. data/lib/active_model_serializers/adapter/json_api/relationship.rb +104 -0
  88. data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +66 -0
  89. data/lib/active_model_serializers/adapter/json_api.rb +533 -0
  90. data/lib/active_model_serializers/adapter/null.rb +9 -0
  91. data/lib/active_model_serializers/adapter.rb +98 -0
  92. data/lib/active_model_serializers/callbacks.rb +55 -0
  93. data/lib/active_model_serializers/deprecate.rb +54 -0
  94. data/lib/active_model_serializers/deserialization.rb +15 -0
  95. data/lib/active_model_serializers/json_pointer.rb +14 -0
  96. data/lib/active_model_serializers/logging.rb +122 -0
  97. data/lib/active_model_serializers/lookup_chain.rb +80 -0
  98. data/lib/active_model_serializers/model.rb +130 -0
  99. data/lib/active_model_serializers/railtie.rb +50 -0
  100. data/lib/active_model_serializers/register_jsonapi_renderer.rb +78 -0
  101. data/lib/active_model_serializers/serializable_resource.rb +82 -0
  102. data/lib/active_model_serializers/serialization_context.rb +39 -0
  103. data/lib/active_model_serializers/test/schema.rb +138 -0
  104. data/lib/active_model_serializers/test/serializer.rb +125 -0
  105. data/lib/active_model_serializers/test.rb +7 -0
  106. data/lib/active_model_serializers.rb +47 -81
  107. data/lib/generators/rails/USAGE +6 -0
  108. data/lib/generators/rails/resource_override.rb +10 -0
  109. data/lib/generators/rails/serializer_generator.rb +36 -0
  110. data/lib/generators/rails/templates/serializer.rb.erb +8 -0
  111. data/lib/grape/active_model_serializers.rb +16 -0
  112. data/lib/grape/formatters/active_model_serializers.rb +32 -0
  113. data/lib/grape/helpers/active_model_serializers.rb +17 -0
  114. data/lib/tasks/rubocop.rake +53 -0
  115. data/test/action_controller/adapter_selector_test.rb +62 -0
  116. data/test/action_controller/explicit_serializer_test.rb +135 -0
  117. data/test/action_controller/json/include_test.rb +246 -0
  118. data/test/action_controller/json_api/deserialization_test.rb +112 -0
  119. data/test/action_controller/json_api/errors_test.rb +40 -0
  120. data/test/action_controller/json_api/fields_test.rb +66 -0
  121. data/test/action_controller/json_api/linked_test.rb +202 -0
  122. data/test/action_controller/json_api/pagination_test.rb +124 -0
  123. data/test/action_controller/json_api/transform_test.rb +189 -0
  124. data/test/action_controller/lookup_proc_test.rb +49 -0
  125. data/test/action_controller/namespace_lookup_test.rb +232 -0
  126. data/test/action_controller/serialization_scope_name_test.rb +235 -0
  127. data/test/action_controller/serialization_test.rb +478 -0
  128. data/test/active_model_serializers/adapter_for_test.rb +208 -0
  129. data/test/active_model_serializers/json_pointer_test.rb +22 -0
  130. data/test/active_model_serializers/logging_test.rb +77 -0
  131. data/test/active_model_serializers/model_test.rb +142 -0
  132. data/test/active_model_serializers/railtie_test_isolated.rb +68 -0
  133. data/test/active_model_serializers/register_jsonapi_renderer_test_isolated.rb +161 -0
  134. data/test/active_model_serializers/serialization_context_test_isolated.rb +71 -0
  135. data/test/active_model_serializers/test/schema_test.rb +131 -0
  136. data/test/active_model_serializers/test/serializer_test.rb +62 -0
  137. data/test/active_record_test.rb +9 -0
  138. data/test/adapter/attributes_test.rb +40 -0
  139. data/test/adapter/deprecation_test.rb +100 -0
  140. data/test/adapter/json/belongs_to_test.rb +45 -0
  141. data/test/adapter/json/collection_test.rb +104 -0
  142. data/test/adapter/json/has_many_test.rb +53 -0
  143. data/test/adapter/json/transform_test.rb +93 -0
  144. data/test/adapter/json_api/belongs_to_test.rb +155 -0
  145. data/test/adapter/json_api/collection_test.rb +96 -0
  146. data/test/adapter/json_api/errors_test.rb +76 -0
  147. data/test/adapter/json_api/fields_test.rb +96 -0
  148. data/test/adapter/json_api/has_many_explicit_serializer_test.rb +96 -0
  149. data/test/adapter/json_api/has_many_test.rb +173 -0
  150. data/test/adapter/json_api/has_one_test.rb +80 -0
  151. data/test/adapter/json_api/include_data_if_sideloaded_test.rb +213 -0
  152. data/test/adapter/json_api/json_api_test.rb +33 -0
  153. data/test/adapter/json_api/linked_test.rb +413 -0
  154. data/test/adapter/json_api/links_test.rb +110 -0
  155. data/test/adapter/json_api/pagination_links_test.rb +206 -0
  156. data/test/adapter/json_api/parse_test.rb +137 -0
  157. data/test/adapter/json_api/relationship_test.rb +397 -0
  158. data/test/adapter/json_api/resource_meta_test.rb +100 -0
  159. data/test/adapter/json_api/toplevel_jsonapi_test.rb +82 -0
  160. data/test/adapter/json_api/transform_test.rb +512 -0
  161. data/test/adapter/json_api/type_test.rb +193 -0
  162. data/test/adapter/json_test.rb +46 -0
  163. data/test/adapter/null_test.rb +22 -0
  164. data/test/adapter/polymorphic_test.rb +218 -0
  165. data/test/adapter_test.rb +67 -0
  166. data/test/array_serializer_test.rb +20 -73
  167. data/test/benchmark/app.rb +65 -0
  168. data/test/benchmark/benchmarking_support.rb +67 -0
  169. data/test/benchmark/bm_active_record.rb +81 -0
  170. data/test/benchmark/bm_adapter.rb +38 -0
  171. data/test/benchmark/bm_caching.rb +119 -0
  172. data/test/benchmark/bm_lookup_chain.rb +83 -0
  173. data/test/benchmark/bm_transform.rb +45 -0
  174. data/test/benchmark/config.ru +3 -0
  175. data/test/benchmark/controllers.rb +83 -0
  176. data/test/benchmark/fixtures.rb +219 -0
  177. data/test/cache_test.rb +651 -0
  178. data/test/collection_serializer_test.rb +127 -0
  179. data/test/fixtures/active_record.rb +113 -0
  180. data/test/fixtures/poro.rb +225 -0
  181. data/test/generators/scaffold_controller_generator_test.rb +24 -0
  182. data/test/generators/serializer_generator_test.rb +75 -0
  183. data/test/grape_test.rb +196 -0
  184. data/test/lint_test.rb +49 -0
  185. data/test/logger_test.rb +20 -0
  186. data/test/poro_test.rb +9 -0
  187. data/test/serializable_resource_test.rb +79 -0
  188. data/test/serializers/association_macros_test.rb +37 -0
  189. data/test/serializers/associations_test.rb +518 -0
  190. data/test/serializers/attribute_test.rb +153 -0
  191. data/test/serializers/attributes_test.rb +52 -0
  192. data/test/serializers/caching_configuration_test_isolated.rb +170 -0
  193. data/test/serializers/configuration_test.rb +32 -0
  194. data/test/serializers/fieldset_test.rb +14 -0
  195. data/test/serializers/meta_test.rb +202 -0
  196. data/test/serializers/options_test.rb +32 -0
  197. data/test/serializers/read_attribute_for_serialization_test.rb +79 -0
  198. data/test/serializers/reflection_test.rb +479 -0
  199. data/test/serializers/root_test.rb +21 -0
  200. data/test/serializers/serialization_test.rb +55 -0
  201. data/test/serializers/serializer_for_test.rb +136 -0
  202. data/test/serializers/serializer_for_with_namespace_test.rb +88 -0
  203. data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
  204. data/test/support/isolated_unit.rb +84 -0
  205. data/test/support/rails5_shims.rb +53 -0
  206. data/test/support/rails_app.rb +38 -0
  207. data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
  208. data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +6 -0
  209. data/test/support/schemas/custom/show.json +7 -0
  210. data/test/support/schemas/hyper_schema.json +93 -0
  211. data/test/support/schemas/render_using_json_api.json +43 -0
  212. data/test/support/schemas/simple_json_pointers.json +10 -0
  213. data/test/support/serialization_testing.rb +79 -0
  214. data/test/test_helper.rb +59 -21
  215. metadata +529 -43
  216. data/DESIGN.textile +0 -586
  217. data/Gemfile.edge +0 -9
  218. data/bench/perf.rb +0 -43
  219. data/cruft.md +0 -19
  220. data/lib/active_model/array_serializer.rb +0 -104
  221. data/lib/active_model/serializer/associations.rb +0 -233
  222. data/lib/active_record/serializer_override.rb +0 -16
  223. data/lib/generators/resource_override.rb +0 -13
  224. data/lib/generators/serializer/USAGE +0 -9
  225. data/lib/generators/serializer/serializer_generator.rb +0 -42
  226. data/lib/generators/serializer/templates/serializer.rb +0 -19
  227. data/test/association_test.rb +0 -592
  228. data/test/caching_test.rb +0 -96
  229. data/test/generators_test.rb +0 -85
  230. data/test/no_serialization_scope_test.rb +0 -34
  231. data/test/serialization_scope_name_test.rb +0 -67
  232. data/test/serialization_test.rb +0 -392
  233. data/test/serializer_support_test.rb +0 -51
  234. data/test/serializer_test.rb +0 -1465
  235. data/test/test_fakes.rb +0 -217
@@ -0,0 +1,265 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # How to migrate from `0.8` to `0.10` safely
4
+
5
+ ## Disclaimer
6
+ ### Proceed at your own risk
7
+ This document attempts to outline steps to upgrade your app based on the collective experience of
8
+ developers who have done this already. It may not cover all edge cases and situations that may cause issues,
9
+ so please proceed with a certain level of caution.
10
+
11
+ ## Overview
12
+ This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
13
+ below has been created via the collective knowledge of contributions of those who have done
14
+ the migration successfully. The method has been tested specifically for migrating from `0.8.3`
15
+ to `0.10.2`.
16
+
17
+ The high level approach is to upgrade to `0.10` and change all serializers to use
18
+ a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
19
+ and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
20
+ functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
21
+ new serializers that don't use these backwards compatible versions and slowly migrate
22
+ existing serializers to the `0.10` versions as needed.
23
+
24
+ ### `0.10` breaking changes
25
+ - Passing a serializer to `render json:` is no longer supported
26
+
27
+ ```ruby
28
+ render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
29
+ ```
30
+
31
+ - Passing a nil resource to serializer now fails
32
+
33
+ ```ruby
34
+ CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
35
+ ```
36
+
37
+ - Attribute methods are no longer defined on the serializer, and must be explicitly
38
+ accessed through `object`
39
+
40
+ ```ruby
41
+ class MySerializer
42
+ attributes :foo, :bar
43
+
44
+ def foo
45
+ bar + 1 # bar does not work, needs to be object.bar in 0.10
46
+ end
47
+ end
48
+ ```
49
+
50
+ - `root` option to collection serializer behaves differently
51
+
52
+ ```ruby
53
+ # in 0.8
54
+ ActiveModel::ArraySerializer.new(resources, root: "resources")
55
+ # resulted in { "resources": <serialized_resources> }, does not work in 0.10
56
+ ```
57
+
58
+ - No default serializer when serializer doesn't exist
59
+ - `@options` changed to `instance_options`
60
+ - Nested relationships are no longer walked by default. Use the `:include` option at **controller `render`** level to specify what relationships to walk. E.g. `render json: @post, include: {comments: :author}` if you want the `author` relationship walked, otherwise the json would only include the post with comments. See: https://github.com/rails-api/active_model_serializers/pull/1127
61
+ - To emulate `0.8`'s walking of arbitrarily deep relationships use: `include: '**'`. E.g. `render json: @post, include: '**'`
62
+
63
+ ## Steps to migrate
64
+
65
+ ### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
66
+ Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`
67
+
68
+ ### 2. Add `ActiveModel::V08::Serializer`
69
+
70
+ ```ruby
71
+ module ActiveModel
72
+ module V08
73
+ class Serializer < ActiveModel::Serializer
74
+ include Rails.application.routes.url_helpers
75
+
76
+ # AMS 0.8 would delegate method calls from within the serializer to the
77
+ # object.
78
+ def method_missing(*args)
79
+ method = args.first
80
+ read_attribute_for_serialization(method)
81
+ end
82
+
83
+ alias_method :options, :instance_options
84
+
85
+ # Since attributes could be read from the `object` via `method_missing`,
86
+ # the `try` method did not behave as before. This patches `try` with the
87
+ # original implementation plus the addition of
88
+ # ` || object.respond_to?(a.first, true)` to check if the object responded to
89
+ # the given method.
90
+ def try(*a, &b)
91
+ if a.empty? || respond_to?(a.first, true) || object.respond_to?(a.first, true)
92
+ try!(*a, &b)
93
+ end
94
+ end
95
+
96
+ # AMS 0.8 would return nil if the serializer was initialized with a nil
97
+ # resource.
98
+ def serializable_hash(adapter_options = nil,
99
+ options = {},
100
+ adapter_instance =
101
+ self.class.serialization_adapter_instance)
102
+ object.nil? ? nil : super
103
+ end
104
+ end
105
+ end
106
+ end
107
+
108
+ ```
109
+ Add this class to your app however you see fit. This is the class that your existing serializers
110
+ that inherit from `ActiveModel::Serializer` should inherit from.
111
+
112
+ ### 3. Add `ActiveModel::V08::CollectionSerializer`
113
+ ```ruby
114
+ module ActiveModel
115
+ module V08
116
+ class CollectionSerializer < ActiveModel::Serializer::CollectionSerializer
117
+ # In AMS 0.8, passing an ArraySerializer instance with a `root` option
118
+ # properly nested the serialized resources within the given root.
119
+ # Ex.
120
+ #
121
+ # class MyController < ActionController::Base
122
+ # def index
123
+ # render json: ActiveModel::Serializer::ArraySerializer
124
+ # .new(resources, root: "resources")
125
+ # end
126
+ # end
127
+ #
128
+ # Produced
129
+ #
130
+ # {
131
+ # "resources": [
132
+ # <serialized_resource>,
133
+ # ...
134
+ # ]
135
+ # }
136
+ def as_json(options = {})
137
+ if root
138
+ {
139
+ root => super
140
+ }
141
+ else
142
+ super
143
+ end
144
+ end
145
+
146
+ # AMS 0.8 used `DefaultSerializer` if it couldn't find a serializer for
147
+ # the given resource. When not using an adapter, this is not true in
148
+ # `0.10`
149
+ def serializer_from_resource(resource, serializer_context_class, options)
150
+ serializer_class =
151
+ options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
152
+
153
+ if serializer_class.nil? # rubocop:disable Style/GuardClause
154
+ DefaultSerializer.new(resource, options)
155
+ else
156
+ serializer_class.new(resource, options.except(:serializer))
157
+ end
158
+ end
159
+
160
+ class DefaultSerializer
161
+ attr_reader :object, :options
162
+
163
+ def initialize(object, options={})
164
+ @object, @options = object, options
165
+ end
166
+
167
+ def serializable_hash
168
+ @object.as_json(@options)
169
+ end
170
+ end
171
+ end
172
+ end
173
+ end
174
+ ```
175
+ Add this class to your app however you see fit. This is the class that existing uses of
176
+ `ActiveModel::ArraySerializer` should be changed to use.
177
+
178
+ ### 4. Add `ActiveModelSerializers::Adapter::V08Adapter`
179
+ ```ruby
180
+ module ActiveModelSerializers
181
+ module Adapter
182
+ class V08Adapter < ActiveModelSerializers::Adapter::Base
183
+ def serializable_hash(options = nil)
184
+ options ||= {}
185
+
186
+ if serializer.respond_to?(:each)
187
+ if serializer.root
188
+ delegate_to_json_adapter(options)
189
+ else
190
+ serializable_hash_for_collection(options)
191
+ end
192
+ else
193
+ serializable_hash_for_single_resource(options)
194
+ end
195
+ end
196
+
197
+ def serializable_hash_for_collection(options)
198
+ serializer.map do |s|
199
+ V08Adapter.new(s, instance_options)
200
+ .serializable_hash(options)
201
+ end
202
+ end
203
+
204
+ def serializable_hash_for_single_resource(options)
205
+ if serializer.object.is_a?(ActiveModel::Serializer)
206
+ # It is recommended that you add some logging here to indicate
207
+ # places that should get converted to eventually allow for this
208
+ # adapter to get removed.
209
+ @serializer = serializer.object
210
+ end
211
+
212
+ if serializer.root
213
+ delegate_to_json_adapter(options)
214
+ else
215
+ options = serialization_options(options)
216
+ serializer.serializable_hash(instance_options, options, self)
217
+ end
218
+ end
219
+
220
+ def delegate_to_json_adapter(options)
221
+ ActiveModelSerializers::Adapter::Json
222
+ .new(serializer, instance_options)
223
+ .serializable_hash(options)
224
+ end
225
+ end
226
+ end
227
+ end
228
+ ```
229
+ Add this class to your app however you see fit.
230
+
231
+ Add
232
+ ```ruby
233
+ ActiveModelSerializers.config.adapter =
234
+ ActiveModelSerializers::Adapter::V08Adapter
235
+ ```
236
+ to `config/active_model_serializer.rb` to configure AMS to use this
237
+ class as the default adapter.
238
+
239
+ ### 5. Change inheritors of `ActiveModel::Serializer` to inherit from `ActiveModel::V08::Serializer`
240
+ Simple find/replace
241
+
242
+ ### 6. Remove `private` keyword from serializers
243
+ Simple find/replace. This is required to allow the `ActiveModel::V08::Serializer`
244
+ to have proper access to the methods defined in the serializer.
245
+
246
+ You may be able to change the `private` to `protected`, but this is hasn't been tested yet.
247
+
248
+ ### 7. Remove references to `ActiveRecord::Base#active_model_serializer`
249
+ This method is no longer supported in `0.10`.
250
+
251
+ `0.10` does a good job of discovering serializers for `ActiveRecord` objects.
252
+
253
+ ### 8. Rename `ActiveModel::ArraySerializer` to `ActiveModel::V08::CollectionSerializer`
254
+ Find/replace uses of `ActiveModel::ArraySerializer` with `ActiveModel::V08::CollectionSerializer`.
255
+
256
+ Also, be sure to change the `each_serializer` keyword to `serializer` when calling making the replacement.
257
+
258
+ ### 9. Replace uses of `@options` to `instance_options` in serializers
259
+ Simple find/replace
260
+
261
+ ## Conclusion
262
+ After you've done the steps above, you should test your app to ensure that everything is still working properly.
263
+
264
+ If you run into issues, please contribute back to this document so others can benefit from your knowledge.
265
+
@@ -0,0 +1,147 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Integrating with Ember and JSON API
4
+
5
+ - [Preparation](./ember-and-json-api.md#preparation)
6
+ - [Server-Side Changes](./ember-and-json-api.md#server-side-changes)
7
+ - [Adapter Changes](./ember-and-json-api.md#adapter-changes)
8
+ - [Serializer Changes](./ember-and-json-api.md#serializer-changes)
9
+ - [Including Nested Resources](./ember-and-json-api.md#including-nested-resources)
10
+
11
+ ## Preparation
12
+
13
+ Note: This guide assumes that `ember-cli` is used for your ember app.
14
+
15
+ The JSON API specification calls for hyphens for multi-word separators. ActiveModelSerializers uses underscores.
16
+ To solve this, in Ember, both the adapter and the serializer will need some modifications:
17
+
18
+ ### Server-Side Changes
19
+
20
+ First, set the adapter type in an initializer file:
21
+
22
+ ```ruby
23
+ # config/initializers/active_model_serializers.rb
24
+ ActiveModelSerializers.config.adapter = :json_api
25
+ ```
26
+
27
+ or:
28
+
29
+ ```ruby
30
+ # config/initializers/active_model_serializers.rb
31
+ ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::JsonApi
32
+ ```
33
+
34
+ You will also want to set the `key_transform` to `:unaltered` since you will adjust the attributes in your Ember serializer to use underscores instead of dashes later. You could also use `:underscore`, but `:unaltered` is better for performance.
35
+
36
+ ```ruby
37
+ # config/initializers/active_model_serializers.rb
38
+ ActiveModelSerializers.config.key_transform = :unaltered
39
+ ```
40
+
41
+ In order to properly handle JSON API responses, we need to register a JSON API renderer, like so:
42
+
43
+ ```ruby
44
+ # config/initializers/active_model_serializers.rb
45
+ ActiveSupport.on_load(:action_controller) do
46
+ require 'active_model_serializers/register_jsonapi_renderer'
47
+ end
48
+ ```
49
+ Rails also requires your controller to tell it that you accept and generate JSONAPI data. To do that, you use `respond_to` in your controller handlers to tell rails you are consuming and returning jsonapi format data. Without this, Rails will refuse to parse the request body into params. You can add `ActionController::MimeResponds` to your application controller to enable this:
50
+
51
+ ```ruby
52
+ class ApplicationController < ActionController::API
53
+ include ActionController::MimeResponds
54
+ end
55
+ ```
56
+ Then, in your controller you can tell rails you're accepting and rendering the jsonapi format:
57
+ ```ruby
58
+ # POST /post
59
+ def create
60
+ @post = Post.new(post_params)
61
+ respond_to do |format|
62
+ if @post.save
63
+ format.jsonapi { render jsonapi: @post, status: :created, location: @post }
64
+ else
65
+ format.jsonapi { render jsonapi: @post.errors, status: :unprocessable_entity }
66
+ end
67
+ end
68
+ end
69
+
70
+ # Only allow a trusted parameter "white list" through.
71
+ def post_params
72
+ ActiveModelSerializers::Deserialization.jsonapi_parse!(params, only: [:title, :body] )
73
+ end
74
+ end
75
+ ```
76
+
77
+ #### Note:
78
+ In Rails 5, the "unsafe" method ( `jsonapi_parse!` vs the safe `jsonapi_parse`) throws an `InvalidDocument` exception when the payload does not meet basic criteria for JSON API deserialization.
79
+
80
+
81
+ ### Adapter Changes
82
+
83
+ ```javascript
84
+ // app/adapters/application.js
85
+ import Ember from 'ember';
86
+ import DS from 'ember-data';
87
+ import ENV from "../config/environment";
88
+ const { underscore, pluralize } = Ember.String;
89
+
90
+ export default DS.JSONAPIAdapter.extend({
91
+ namespace: 'api',
92
+ // if your rails app is on a different port from your ember app
93
+ // this can be helpful for development.
94
+ // in production, the host for both rails and ember should be the same.
95
+ host: ENV.host,
96
+
97
+ // allows the multiword paths in urls to be underscored
98
+ pathForType: function(type) {
99
+ let underscored = underscore(type);
100
+ return pluralize(underscored);
101
+ },
102
+
103
+ });
104
+ ```
105
+
106
+ ### Serializer Changes
107
+
108
+ ```javascript
109
+ // app/serializers/application.js
110
+ import Ember from 'ember';
111
+ import DS from 'ember-data';
112
+ var underscore = Ember.String.underscore;
113
+
114
+ export default DS.JSONAPISerializer.extend({
115
+ keyForAttribute: function(attr) {
116
+ return underscore(attr);
117
+ },
118
+
119
+ keyForRelationship: function(rawKey) {
120
+ return underscore(rawKey);
121
+ }
122
+ });
123
+
124
+ ```
125
+
126
+
127
+ ## Including Nested Resources
128
+
129
+ Ember Data can request related records by using `include`. Below are some examples of how to make Ember Data request the inclusion of related records. For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
130
+
131
+ ```javascript
132
+ store.findRecord('post', postId, { include: 'comments' } );
133
+ ```
134
+ which will generate the path /posts/{postId}?include='comments'
135
+
136
+ So then in your controller, you'll want to be sure to have something like:
137
+ ```ruby
138
+ render jsonapi: @post, include: params[:include]
139
+ ```
140
+
141
+ If you want to use `include` on a collection, you'd write something like this:
142
+
143
+ ```javascript
144
+ store.query('post', { include: 'comments' });
145
+ ```
146
+
147
+ which will generate the path `/posts?include='comments'`
@@ -0,0 +1,19 @@
1
+ # Integration with Grape
2
+
3
+ [Grape](https://github.com/ruby-grape/grape) is an opinionated micro-framework for creating REST-like APIs in ruby.
4
+
5
+ ActiveModelSerializers currently supports Grape >= 0.13, < 1.0
6
+
7
+ To add [Grape](https://github.com/ruby-grape/grape) support, enable the formatter and helper functions by including `Grape::ActiveModelSerializers` in your base endpoint. For example:
8
+
9
+ ```ruby
10
+ module Example
11
+ class Dummy < Grape::API
12
+ require 'grape/active_model_serializers'
13
+ include Grape::ActiveModelSerializers
14
+ mount Example::V1::Base
15
+ end
16
+ end
17
+ ```
18
+
19
+ Aside from this, [configuration](../general/configuration_options.md) of ActiveModelSerializers is exactly the same.
@@ -0,0 +1,56 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # [JSON API Errors](http://jsonapi.org/format/#errors)
4
+
5
+ Rendering error documents requires specifying the error serializer(s):
6
+
7
+ - Serializer:
8
+ - For a single resource: `serializer: ActiveModel::Serializer::ErrorSerializer`.
9
+ - For a collection: `serializer: ActiveModel::Serializer::ErrorsSerializer`, `each_serializer: ActiveModel::Serializer::ErrorSerializer`.
10
+
11
+ The resource **MUST** have a non-empty associated `#errors` object.
12
+ The `errors` object must have a `#messages` method that returns a hash of error name to array of
13
+ descriptions.
14
+
15
+ ## Use in controllers
16
+
17
+ ```ruby
18
+ resource = Profile.new(name: 'Name 1',
19
+ description: 'Description 1',
20
+ comments: 'Comments 1')
21
+ resource.errors.add(:name, 'cannot be nil')
22
+ resource.errors.add(:name, 'must be longer')
23
+ resource.errors.add(:id, 'must be a uuid')
24
+
25
+ render json: resource, status: 422, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
26
+ # #=>
27
+ # { :errors =>
28
+ # [
29
+ # { :source => { :pointer => '/data/attributes/name' }, :detail => 'cannot be nil' },
30
+ # { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be longer' },
31
+ # { :source => { :pointer => '/data/attributes/id' }, :detail => 'must be a uuid' }
32
+ # ]
33
+ # }.to_json
34
+ ```
35
+
36
+ ## Direct error document generation
37
+
38
+ ```ruby
39
+ options = nil
40
+ resource = ModelWithErrors.new
41
+ resource.errors.add(:name, 'must be awesome')
42
+
43
+ serializable_resource = ActiveModelSerializers::SerializableResource.new(
44
+ resource, {
45
+ serializer: ActiveModel::Serializer::ErrorSerializer,
46
+ adapter: :json_api
47
+ })
48
+ serializable_resource.as_json(options)
49
+ # #=>
50
+ # {
51
+ # :errors =>
52
+ # [
53
+ # { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be awesome' }
54
+ # ]
55
+ # }
56
+ ```