JR by default uses some simple rules to format (and unformat) an attribute for (de-)serialization. Strings and Integers are output to JSON as is, and all other values have
.to_s applied to them. This outputs something in all cases, but it is certainly not correct for every situation.
If you want to change the way an attribute is (de-)serialized, you have a couple of ways. The simplest method is to create a getter (and setter) method on the resource that overrides the attribute and applies the (un-)formatting there. For example:
This is simple to implement for a one-off situation. But in this example, it wouldn’t be good if you wanted to apply the same formatting rules to all DateTime fields in your system. Another issue is the attribute on the resource will always return a formatted response, whether you want it or not.
To overcome the above limitations, JR uses Value Formatters. Value Formatters allow you to control the way values are handled for an attribute. The
format can be set per attribute as it is declared in the resource. For example:
A Value formatter has a
format and an
unformat method. Here’s the base ValueFormatter and DefaultValueFormatter for reference:
You can also create your own Value Formatter. Value Formatters must be named with the
format name followed by
DateWithUTCTimezoneValueFormatter, and derive from
JSONAPI::ValueFormatter. It is recommended that you create a directory for your formatters, called
format method is called by the
ResourceSerializer as it is serializing a resource. The
format method takes the
raw_value is the value as read from the model.
unformat method is called when processing the request. Each incoming attribute (except
links) are run through the
unformat method. The
unformat method takes a
value, which is the value as it comes in on the request. This allows you process the incoming value to alter its state before it is stored in the model.
Another way to handle formatting is to set a different default value formatter. This will affect all attributes that do not have a
format set. You can do this by overriding the
default_attribute_options method for a resource (or a base resource for a system wide change).
This way all DateTime values will be formatted to display in the UTC timezone.
By default, JR uses dasherized keys as per the JSON API naming recommendations. This can be changed by specifying a different key formatter.
For example, to use camel cased keys with an initial lowercase character (JSON’s default), create an initializer and add the following:
This will cause the serializer to use the
CamelizedKeyFormatter. You can also create your own
KeyFormatter, for example:
You would specify this in