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.
- checksums.yaml +5 -5
- data/.github/ISSUE_TEMPLATE.md +29 -0
- data/.github/PULL_REQUEST_TEMPLATE.md +15 -0
- data/.gitignore +17 -0
- data/.rubocop.yml +105 -0
- data/.simplecov +110 -0
- data/.travis.yml +50 -24
- data/CHANGELOG.md +650 -6
- data/CODE_OF_CONDUCT.md +74 -0
- data/CONTRIBUTING.md +105 -0
- data/Gemfile +69 -1
- data/{MIT-LICENSE.txt → MIT-LICENSE} +3 -2
- data/README.md +195 -545
- data/Rakefile +64 -8
- data/active_model_serializers.gemspec +62 -23
- data/appveyor.yml +28 -0
- data/bin/bench +171 -0
- data/bin/bench_regression +316 -0
- data/bin/rubocop +38 -0
- data/bin/serve_benchmark +39 -0
- data/docs/README.md +41 -0
- data/docs/STYLE.md +58 -0
- data/docs/general/adapters.md +269 -0
- data/docs/general/caching.md +58 -0
- data/docs/general/configuration_options.md +185 -0
- data/docs/general/deserialization.md +100 -0
- data/docs/general/fields.md +31 -0
- data/docs/general/getting_started.md +133 -0
- data/docs/general/instrumentation.md +40 -0
- data/docs/general/key_transforms.md +40 -0
- data/docs/general/logging.md +21 -0
- data/docs/general/rendering.md +293 -0
- data/docs/general/serializers.md +495 -0
- data/docs/how-open-source-maintained.jpg +0 -0
- data/docs/howto/add_pagination_links.md +138 -0
- data/docs/howto/add_relationship_links.md +140 -0
- data/docs/howto/add_root_key.md +62 -0
- data/docs/howto/grape_integration.md +42 -0
- data/docs/howto/outside_controller_use.md +66 -0
- data/docs/howto/passing_arbitrary_options.md +27 -0
- data/docs/howto/serialize_poro.md +73 -0
- data/docs/howto/test.md +154 -0
- data/docs/howto/upgrade_from_0_8_to_0_10.md +265 -0
- data/docs/integrations/ember-and-json-api.md +147 -0
- data/docs/integrations/grape.md +19 -0
- data/docs/jsonapi/errors.md +56 -0
- data/docs/jsonapi/schema/schema.json +366 -0
- data/docs/jsonapi/schema.md +151 -0
- data/docs/rfcs/0000-namespace.md +106 -0
- data/docs/rfcs/template.md +15 -0
- data/lib/action_controller/serialization.rb +43 -38
- data/lib/active_model/serializable_resource.rb +11 -0
- data/lib/active_model/serializer/adapter/attributes.rb +15 -0
- data/lib/active_model/serializer/adapter/base.rb +18 -0
- data/lib/active_model/serializer/adapter/json.rb +15 -0
- data/lib/active_model/serializer/adapter/json_api.rb +15 -0
- data/lib/active_model/serializer/adapter/null.rb +15 -0
- data/lib/active_model/serializer/adapter.rb +24 -0
- data/lib/active_model/serializer/array_serializer.rb +12 -0
- data/lib/active_model/serializer/association.rb +71 -0
- data/lib/active_model/serializer/attribute.rb +25 -0
- data/lib/active_model/serializer/belongs_to_reflection.rb +11 -0
- data/lib/active_model/serializer/collection_serializer.rb +88 -0
- data/lib/active_model/serializer/concerns/caching.rb +300 -0
- data/lib/active_model/serializer/error_serializer.rb +14 -0
- data/lib/active_model/serializer/errors_serializer.rb +32 -0
- data/lib/active_model/serializer/field.rb +90 -0
- data/lib/active_model/serializer/fieldset.rb +31 -0
- data/lib/active_model/serializer/has_many_reflection.rb +10 -0
- data/lib/active_model/serializer/has_one_reflection.rb +7 -0
- data/lib/active_model/serializer/lazy_association.rb +96 -0
- data/lib/active_model/serializer/link.rb +21 -0
- data/lib/active_model/serializer/lint.rb +150 -0
- data/lib/active_model/serializer/null.rb +17 -0
- data/lib/active_model/serializer/reflection.rb +210 -0
- data/lib/active_model/{serializers → serializer}/version.rb +1 -1
- data/lib/active_model/serializer.rb +343 -442
- data/lib/active_model_serializers/adapter/attributes.rb +13 -0
- data/lib/active_model_serializers/adapter/base.rb +83 -0
- data/lib/active_model_serializers/adapter/json.rb +21 -0
- data/lib/active_model_serializers/adapter/json_api/deserialization.rb +213 -0
- data/lib/active_model_serializers/adapter/json_api/error.rb +96 -0
- data/lib/active_model_serializers/adapter/json_api/jsonapi.rb +49 -0
- data/lib/active_model_serializers/adapter/json_api/link.rb +83 -0
- data/lib/active_model_serializers/adapter/json_api/meta.rb +37 -0
- data/lib/active_model_serializers/adapter/json_api/pagination_links.rb +88 -0
- data/lib/active_model_serializers/adapter/json_api/relationship.rb +104 -0
- data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +66 -0
- data/lib/active_model_serializers/adapter/json_api.rb +533 -0
- data/lib/active_model_serializers/adapter/null.rb +9 -0
- data/lib/active_model_serializers/adapter.rb +98 -0
- data/lib/active_model_serializers/callbacks.rb +55 -0
- data/lib/active_model_serializers/deprecate.rb +54 -0
- data/lib/active_model_serializers/deserialization.rb +15 -0
- data/lib/active_model_serializers/json_pointer.rb +14 -0
- data/lib/active_model_serializers/logging.rb +122 -0
- data/lib/active_model_serializers/lookup_chain.rb +80 -0
- data/lib/active_model_serializers/model.rb +130 -0
- data/lib/active_model_serializers/railtie.rb +50 -0
- data/lib/active_model_serializers/register_jsonapi_renderer.rb +78 -0
- data/lib/active_model_serializers/serializable_resource.rb +82 -0
- data/lib/active_model_serializers/serialization_context.rb +39 -0
- data/lib/active_model_serializers/test/schema.rb +138 -0
- data/lib/active_model_serializers/test/serializer.rb +125 -0
- data/lib/active_model_serializers/test.rb +7 -0
- data/lib/active_model_serializers.rb +47 -81
- data/lib/generators/rails/USAGE +6 -0
- data/lib/generators/rails/resource_override.rb +10 -0
- data/lib/generators/rails/serializer_generator.rb +36 -0
- data/lib/generators/rails/templates/serializer.rb.erb +8 -0
- data/lib/grape/active_model_serializers.rb +16 -0
- data/lib/grape/formatters/active_model_serializers.rb +32 -0
- data/lib/grape/helpers/active_model_serializers.rb +17 -0
- data/lib/tasks/rubocop.rake +53 -0
- data/test/action_controller/adapter_selector_test.rb +62 -0
- data/test/action_controller/explicit_serializer_test.rb +135 -0
- data/test/action_controller/json/include_test.rb +246 -0
- data/test/action_controller/json_api/deserialization_test.rb +112 -0
- data/test/action_controller/json_api/errors_test.rb +40 -0
- data/test/action_controller/json_api/fields_test.rb +66 -0
- data/test/action_controller/json_api/linked_test.rb +202 -0
- data/test/action_controller/json_api/pagination_test.rb +124 -0
- data/test/action_controller/json_api/transform_test.rb +189 -0
- data/test/action_controller/lookup_proc_test.rb +49 -0
- data/test/action_controller/namespace_lookup_test.rb +232 -0
- data/test/action_controller/serialization_scope_name_test.rb +235 -0
- data/test/action_controller/serialization_test.rb +478 -0
- data/test/active_model_serializers/adapter_for_test.rb +208 -0
- data/test/active_model_serializers/json_pointer_test.rb +22 -0
- data/test/active_model_serializers/logging_test.rb +77 -0
- data/test/active_model_serializers/model_test.rb +142 -0
- data/test/active_model_serializers/railtie_test_isolated.rb +68 -0
- data/test/active_model_serializers/register_jsonapi_renderer_test_isolated.rb +161 -0
- data/test/active_model_serializers/serialization_context_test_isolated.rb +71 -0
- data/test/active_model_serializers/test/schema_test.rb +131 -0
- data/test/active_model_serializers/test/serializer_test.rb +62 -0
- data/test/active_record_test.rb +9 -0
- data/test/adapter/attributes_test.rb +40 -0
- data/test/adapter/deprecation_test.rb +100 -0
- data/test/adapter/json/belongs_to_test.rb +45 -0
- data/test/adapter/json/collection_test.rb +104 -0
- data/test/adapter/json/has_many_test.rb +53 -0
- data/test/adapter/json/transform_test.rb +93 -0
- data/test/adapter/json_api/belongs_to_test.rb +155 -0
- data/test/adapter/json_api/collection_test.rb +96 -0
- data/test/adapter/json_api/errors_test.rb +76 -0
- data/test/adapter/json_api/fields_test.rb +96 -0
- data/test/adapter/json_api/has_many_explicit_serializer_test.rb +96 -0
- data/test/adapter/json_api/has_many_test.rb +173 -0
- data/test/adapter/json_api/has_one_test.rb +80 -0
- data/test/adapter/json_api/include_data_if_sideloaded_test.rb +213 -0
- data/test/adapter/json_api/json_api_test.rb +33 -0
- data/test/adapter/json_api/linked_test.rb +413 -0
- data/test/adapter/json_api/links_test.rb +110 -0
- data/test/adapter/json_api/pagination_links_test.rb +206 -0
- data/test/adapter/json_api/parse_test.rb +137 -0
- data/test/adapter/json_api/relationship_test.rb +397 -0
- data/test/adapter/json_api/resource_meta_test.rb +100 -0
- data/test/adapter/json_api/toplevel_jsonapi_test.rb +82 -0
- data/test/adapter/json_api/transform_test.rb +512 -0
- data/test/adapter/json_api/type_test.rb +193 -0
- data/test/adapter/json_test.rb +46 -0
- data/test/adapter/null_test.rb +22 -0
- data/test/adapter/polymorphic_test.rb +218 -0
- data/test/adapter_test.rb +67 -0
- data/test/array_serializer_test.rb +20 -73
- data/test/benchmark/app.rb +65 -0
- data/test/benchmark/benchmarking_support.rb +67 -0
- data/test/benchmark/bm_active_record.rb +81 -0
- data/test/benchmark/bm_adapter.rb +38 -0
- data/test/benchmark/bm_caching.rb +119 -0
- data/test/benchmark/bm_lookup_chain.rb +83 -0
- data/test/benchmark/bm_transform.rb +45 -0
- data/test/benchmark/config.ru +3 -0
- data/test/benchmark/controllers.rb +83 -0
- data/test/benchmark/fixtures.rb +219 -0
- data/test/cache_test.rb +651 -0
- data/test/collection_serializer_test.rb +127 -0
- data/test/fixtures/active_record.rb +113 -0
- data/test/fixtures/poro.rb +225 -0
- data/test/generators/scaffold_controller_generator_test.rb +24 -0
- data/test/generators/serializer_generator_test.rb +75 -0
- data/test/grape_test.rb +196 -0
- data/test/lint_test.rb +49 -0
- data/test/logger_test.rb +20 -0
- data/test/poro_test.rb +9 -0
- data/test/serializable_resource_test.rb +79 -0
- data/test/serializers/association_macros_test.rb +37 -0
- data/test/serializers/associations_test.rb +518 -0
- data/test/serializers/attribute_test.rb +153 -0
- data/test/serializers/attributes_test.rb +52 -0
- data/test/serializers/caching_configuration_test_isolated.rb +170 -0
- data/test/serializers/configuration_test.rb +32 -0
- data/test/serializers/fieldset_test.rb +14 -0
- data/test/serializers/meta_test.rb +202 -0
- data/test/serializers/options_test.rb +32 -0
- data/test/serializers/read_attribute_for_serialization_test.rb +79 -0
- data/test/serializers/reflection_test.rb +479 -0
- data/test/serializers/root_test.rb +21 -0
- data/test/serializers/serialization_test.rb +55 -0
- data/test/serializers/serializer_for_test.rb +136 -0
- data/test/serializers/serializer_for_with_namespace_test.rb +88 -0
- data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
- data/test/support/isolated_unit.rb +84 -0
- data/test/support/rails5_shims.rb +53 -0
- data/test/support/rails_app.rb +38 -0
- data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
- data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +6 -0
- data/test/support/schemas/custom/show.json +7 -0
- data/test/support/schemas/hyper_schema.json +93 -0
- data/test/support/schemas/render_using_json_api.json +43 -0
- data/test/support/schemas/simple_json_pointers.json +10 -0
- data/test/support/serialization_testing.rb +79 -0
- data/test/test_helper.rb +59 -21
- metadata +529 -43
- data/DESIGN.textile +0 -586
- data/Gemfile.edge +0 -9
- data/bench/perf.rb +0 -43
- data/cruft.md +0 -19
- data/lib/active_model/array_serializer.rb +0 -104
- data/lib/active_model/serializer/associations.rb +0 -233
- data/lib/active_record/serializer_override.rb +0 -16
- data/lib/generators/resource_override.rb +0 -13
- data/lib/generators/serializer/USAGE +0 -9
- data/lib/generators/serializer/serializer_generator.rb +0 -42
- data/lib/generators/serializer/templates/serializer.rb +0 -19
- data/test/association_test.rb +0 -592
- data/test/caching_test.rb +0 -96
- data/test/generators_test.rb +0 -85
- data/test/no_serialization_scope_test.rb +0 -34
- data/test/serialization_scope_name_test.rb +0 -67
- data/test/serialization_test.rb +0 -392
- data/test/serializer_support_test.rb +0 -51
- data/test/serializer_test.rb +0 -1465
- 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
|
+
```
|