# MediaTypes::Serialization
[](https://travis-ci.com/XPBytes/media_types-serialization)
[](https://badge.fury.io/rb/media_types-serialization)
[](http://opensource.org/licenses/MIT)
`respond_to` on steroids. Add [HATEOAS](https://docs.delftsolutions.nl/wiki/HATEOAS_API) compatible serialization and deserialization to your Rails projects.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'media_types-serialization'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install media_types-serialization
## Usage
Serializers help you in converting a ruby object to a representation matching a specified [Media Type validator](https://github.com/SleeplessByte/media-types-ruby) and the other way around.
### Creating a serializer
```ruby
class BookSerializer < MediaTypes::Serialization::Base
unvalidated 'application/vnd.acme.book'
# outputs with a Content-Type of application/vnd.acme.book.v1+json
output version: 1 do |obj, version, context|
{
book: {
title: obj.title
}
}
end
end
```
To convert a ruby object to a json representation:
```ruby
class Book
attr_accessor :title
end
book = Book.new
book.title = 'Everything, abridged'
BookSerializer.serialize(book, 'vnd.acme.book.v1+json', context: nil)
# => { "book": { "title": "Everything, abridged" } }
```
### Controller integration
You can integrate the serialization system in rails, giving you automatic [Content-Type negotiation](https://en.wikipedia.org/wiki/Content_negotiation) using the `Accept` header:
```ruby
require 'media_types/serialization'
class BookController < ActionController::API
include MediaTypes::Serialization
allow_output_serializer(BookSerializer, only: %i[show])
freeze_io!
def show
book = Book.new
book.title = 'Everything, abridged'
render_media book
end
end
```
While using the controller integration the context will always be set to the current controller.
This allows you to construct urls.
### Adding HATEOAS responses to existing routes
When creating a mobile application it's often useful to allow the app to request a non-html representation of a specific url.
If you have an existing route:
```ruby
class BookController < ApplicationController
def show
@book = Book.new
# Use view corresponding to the controller
end
end
```
You can add a json representation as follows:
```ruby
class BookController < ApplicationController
allow_output_serializer(BookSerializer, only: %i[show])
allow_output_html
freeze_io!
def show
@book = Book.new
render_media @book
end
end
```
### Validations
Right now the serializer does not validate incoming or outgoing information.
This can cause issues when you accidentally emit non-conforming data that people start to depend on.
To make sure you don't do that you can specify a [Media Type validator](https://github.com/SleeplessByte/media-types-ruby):
```ruby
require 'media_types'
class BookValidator
include MediaTypes::Dsl
def self.organisation
'acme'
end
use_name 'book'
validations do
version 1 do
attribute :book do
attribute :title, String
end
end
end
end
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
# outputs with a Content-Type of application/vnd.acme.book.v1+json
output version: 1 do |obj, version, context|
{
book: {
title: obj.title
}
}
end
end
```
For more information, see the [Media Types docs](https://github.com/SleeplessByte/media-types-ruby).
### Versioning
To help with supporting older versions, serializers have a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) to construct json objects:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2] do |obj, version, context|
attribute :book do
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
end
```
```ruby
BookSerializer.serialize(book, BookValidator.version(1), context: nil)
# => { "book": { "title": "Everything, abridged" } }
BookSerializer.serialize(book, BookValidator.version(2), context: nil)
# => { "book": { "title": "Everything, abridged", "description": "Mu" } }
```
### Links
When making [HATEOAS](https://docs.delftsolutions.nl/wiki/HATEOAS_API) compliant applications it's very useful to include `Link` headers in your response so clients can use a `HEAD` request instead of having to fetch the entire resource.
Serializers have convenience methods to help with this:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
end
```
This returns the following response:
```ruby
BookSerializer.serialize(book, BookValidator.version(3), context: controller)
# header = Link: ; rel="self"
# => {
# "book": {
# "_links": {
# "self": { "href": "https://example.org" }
# },
# "title": "Everything, abridged",
# "description": "Mu"
# }
# }
```
### Collections
There are convenience methods for serializing arrays of objects based on a template.
#### Indexes
An index is a collection of urls that point to members of the array.
The index method automatically generates it based on the self links defined in the default view of the same version.
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
output view: :index, version: 3 do |arr, version, context|
attribute :books do
link :self, href: context.book_index_url
index arr, version: version
end
end
end
```
```ruby
BookSerializer.serialize([book], BookValidator.view(:index).version(3), context: controller)
# header = Link: ; rel="self"
# => {
# "books": {
# "_links": {
# "self": { "href": "https://example.org" }
# },
# "_index": [
# { "href": "https://example.org" }
# ]
# }
# }
```
#### Collections
A collection inlines the member objects.
The collection method automatically generates it based on the default view of the same version.
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
output view: :index, version: 3 do |arr, version, context|
attribute :books do
link :self, href: context.book_index_url
index arr, version: version
end
end
output view: :collection, version: 3 do |arr, version, context|
attribute :books do
link :self, href: context.book_collection_url
collection arr, version: version
end
end
end
```
```ruby
BookSerializer.serialize([book], BookValidator.view(:collection).version(3), context: controller)
# header = Link: ; rel="self"
# => {
# "books": {
# "_links": {
# "self": { "href": "https://example.org" }
# },
# "_embedded": [
# {
# "_links": {
# "self": { "href": "https://example.org" }
# },
# "title": "Everything, abridged",
# "description": "Mu"
# }
# ]
# }
# }
```
### Input deserialization
You can mark a media type as something that's allowed to be sent along with a PUT request as follows:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
input version: 3
end
class BookController < ActionController::API
include MediaTypes::Serialization
allow_output_serializer(BookSerializer, only: %i[show])
allow_input_serializer(BookSerializer, only: %i[create])
freeze_io!
def show
book = Book.new
book.title = 'Everything, abridged'
render_media serialize_media(book)
end
def create
json = deserialize(request) # does validation for us
puts json
end
end
```
If you use [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) you might want to convert the verified json data during deserialization:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
input versions: [1, 2, 3] do |json, version, context|
book = Book.new
book.title = json['book']['title']
book.description = 'Not available'
book.description = json['book']['description'] if version >= 2
# Best practise is to only save in the controller.
book
end
end
class BookController < ActionController::API
include MediaTypes::Serialization
allow_output_serializer(BookSerializer, only: %i[show])
allow_input_serializer(BookSerializer, only: %i[create])
freeze_io!
def show
book = Book.new
book.title = 'Everything, abridged'
render_media serialize_media(book)
end
def create
book = deserialize(request)
book.save!
render_media serialize_media(book)
end
end
```
If you don't want to apply any input validation or deserialization you can use the `allow_all_input` method instead of `allow_input_serialization`.
### Raw output
Sometimes you need to output raw data.
This cannot be validated.
You do this as follows:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output_raw view: :raw, version: 3 do |obj, version, context|
hidden do
# Make sure links are only set in the headers, not in the body.
link :self, href: context.book_url(obj)
end
"I'm a non-json output"
end
end
```
### Raw input
You can do the same with input:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
input_raw view: raw, version: 3 do |bytes, version, context|
book = Book.new
book.description = bytes
book
end
end
```
### Remapping media type identifiers
Sometimes you already have old clients using an `application/json` media type identifier when they do requests.
While this is not a good practise as this makes it hard to add new fields or remove old ones, this library has support for migrating away:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
output_alias 'application/json' # maps application/json to to applicaton/vnd.acme.book.v1+json
input view: :create, versions: [1, 2, 3] do |json, version, context|
book = Book.new
book.title = json['book']['title']
book.description = 'Not available'
book.description = json['book']['description'] if version >= 2
# Make sure not to save here but only save in the controller
book
end
input_alias 'application/json', view: :create # maps application/json to to applicaton/vnd.acme.book.v1+json
```
Validation will be done using the remapped validator. Aliasses map to version `nil` if that is available or `1` otherwise. It is not possible to configure this version.
### HTML
This library has a built in API viewer.
The viewer can be accessed by by appending a `?api_viewer=last` query parameter to the URL.
To enable the API viewer, use: `allow_api_viewer` in the controller.
```ruby
class BookController < ActionController::API
include MediaTypes::Serialization
allow_api_viewer
allow_output_serializer(BookSerializer, only: %i[show])
allow_input_serializer(BookSerializer, only: %i[create])
freeze_io!
def show
book = Book.new
book.title = 'Everything, abridged'
render_media serialize_media(book)
end
def create
json = deserialize(request) # does validation for us
puts json
end
end
```
You can also output custom HTML:
```ruby
class BookSerializer < MediaTypes::Serialization::Base
validator BookValidator
output versions: [1, 2, 3] do |obj, version, context|
attribute :book do
link :self, href: context.book_url(obj) if version >= 3
attribute :title, obj.title
attribute :description, obj.description if version >= 2
end
end
output_raw view: :html do |obj, context|
render_view 'book/show', context: context, assigns: {
title: obj.title,
description: obj.description
}
end
output_alias 'text/html', view: :html
end
```
#### Errors
This library adds support for returning errors to clients using the [`application/problem+json`](https://tools.ietf.org/html/rfc7231) media type.
You can catch and transform application errors by adding an `output_error` call before `freeze_io!`:
```ruby
class BookController < ActionController::API
include MediaTypes::Serialization
output_error CanCan::AccessDenied do |problem_output, error|
problem_output.title 'You do not have enough permissions to perform this action.', lang: 'en'
problem_output.title 'Je hebt geen toestemming om deze actie uit te voeren.', lang: 'nl-NL'
problem_output.status_code :forbidden
end
freeze_io!
# ...
end
```
The exception you specified will be rescued by the controller and will be displayed to the user along with a link to the shared wiki page for that error type. Feel free to add instructions there on how clients should solve this problem.
You can find more information at: [https://docs.delftsolutions.nl/wiki/Error](https://docs.delftsolutions.nl/wiki/Error)
If you want to override this url you can use the `problem_output.url(href)` function.
By default the `message` property of the error is used to fill the `details` field.
You can override this by using the `problem_output.override_details(description, lang:)` function.
Custom attributes can be added using the `problem_output.attribute(name, value)` function.
### Related
- [`MediaTypes`](https://github.com/SleeplessByte/media-types-ruby): :gem: Library to create media type validators.
## API
### Serializer definition
These methods become available during class definition if you inherit from `MediaTypes::Serialization::Base`.
#### `unvalidated( prefix )`
Disabled validation for this serializer. Prefix is of the form `application/vnd..`.
Either unvalidated or validator must be used while defining a serializer.
#### `validator( media_type_validator )`
Enabled validation for this serializer using a [Media Type Validator](https://github.com/SleeplessByte/media-types-ruby).
Either validator or unvalidated must be used while defining a serializer.
#### `output( view:, version:, versions: ) do |obj, version, context|`
Defines a serialization block. Either version or versions can be set.
View should be a symbol or unset.
Obj is the object to be serialized, version is the negotiated version and context is the context passed in from the serialize function.
When using the controller integration, context is the current controller.
The block should return an object to convert into JSON.
#### `output_raw( view:, version:, versions: ) do |obj, version, context|`
This has the same behavior as `output` but should return a string instead of an object.
Output is not validated.
#### `output_alias( media_type_identifier, view:, hide_variant: false )`
Defines a legacy mapping. This will make the deserializer parse the media type `media_type_identifier` as if it was version `nil` of the specified view.
If `view` is undefined it will use the output serializer without a view defined.
Response will have a content type equal to `[media_type_identifier]; variant=[mapped_media_type_identifier]`.
If `hide_variant:` is true, the content type emitted will only be `[media_type_identifier]`.
> You cannot alias a _versioned_ media type, otherwise it would be easy to later break the definition by changing the version it aliases.
#### `output_alias_optional( media_type_identifier, view:, hide_variant: false )`
Has the same behavior as `output_alias` but can be used by multiple serializers.
The serializer that is loaded last in the controller 'wins' control over this media type identifier.
If any of the serializers have an `output_alias` defined with the same media type identifier that one will win instead.
Response will have a content type equal to `[media_type_identifier]; variant=[mapped_media_type_identifier]`. If `hide_variant:` is true, the content type emitted will only be `[media_type_identifier]`.
#### `input( view:, version:, versions: ) do |obj, version, context|`
Defines a deserialization block. Either version or versions can be set.
View should be a symbol or unset.
Obj is the object to be serialized, version is the negotiated version and context is the context passed in from the serialize function.
When using the controller integration, context is the current controller.
The block should return the internal representation of the object.
Best practise is to make sure not to change state in this function but to leave that up to the controller.
#### `input_raw( view:, version:, versions: ) do |bytes, version, context|`
This has the same behavior as `input` but takes in raw data. Input is not validated.
#### `input_alias( media_type_identifier, view: )`
Defines a legacy mapping.
This will make the serializer parse the media type `media_type_identifier` as if it was version `nil` of the specified view.
If view is undefined it will use the input serializer without a view defined.
> You cannot alias a _versioned_ media type, otherwise it would be easy to later break the definition by changing the version it aliases.
#### `input_alias_optional( media_type_identifier, view: )`
Has the same behavior as `input_alias` but can be used by multiple serializers.
The serializer that is loaded last in the controller 'wins' control over this media type identifier.
If any of the serializers have an `input_alias` defined with the same media type identifier that one will win instead.
#### `disable_wildcards`
Disables registering wildcard media types.
### Serializer definition
The following methods are available within an `output ... do` block.
#### `attribute( key, value = {} ) do`
Sets a value for the given key.
If a block is given, any `attribute`, `link`, `collection` and `index` statements are run in context of `value`.
Returns the built up context so far.
#### `link( rel, href:, emit_header: true, **attributes )`
Adds a `_link` block to the current context. Also adds the specified link to the HTTP Link header.
`attributes` allows passing in custom attributes.
If `emit_header` is `true` the link will also be emitted as a http header.
Returns the built up context so far.
#### `index( array, serializer, version:, view: nil )`
Adds an `_index` block to the current context. Uses the self links of the specified view to construct an index of urls to the child objects.
Returns the built up context so far.
#### `collection( array, serializer, version:, view: nil )`
Adds an `_embedded` block to the current context. Uses the specified serializer to embed the child objects.
Optionally a block can be used to modify the output from the child serializer.
Returns the built up context so far.
#### `hidden do`
Sometimes you want to add links without actually modifying the object.
Calls to `attribute`, `link`, `index`, `collection` made inside this block won't modify the context.
Any calls to link will only set the HTTP Link header.
Returns the unmodified context.
#### `emit`
Can be added to the end of a block to fix up the return value to return the built up context so far.
Returns the built up context so far.
#### `object do`
Runs a block in a new context and returns the result
#### `render_view( view, context:, **args)`
Can be used to render a view. You can set local variables in the view by assigning a hash to the `assigns:` parameter.
### Controller definition
These functions are available during the controller definition if you add `include MediaTypes::Serialization`.
#### `allow_output_serializer( serializer, views: nil, **filters )`
Configure the controller to allow the client to request responses emitted by the specified serializer.
Optionally allows you to specify which views to allow by passing an array in the views parameter.
Accepts the same filters as `before_action`.
#### `allow_output_html( as: nil, view: nil, layout: nil, **filters )`
Allows falling back to the default Rails view rendering when the client asks for the media type in the `as:` parameter or `text/html` if `as:` is unset.
The `Content-Type` of the response will be `text/html` if the `as:` parameter is unset.
If the `as:` parameter is set, it will include it in the variant parameter: `text/html; variant=application/vnd.xpbytes.borderless`.
Accepts the same filters as `before_action`.
You can set the template to use using the `view:` parameter.
#### `allow_output_docs( description, **filters )`
Outputs the specified description as help information.
Accepts the same filters as `before_action`.
#### `allow_input_serializer( serializer, views: nil, **filters )`
Configure the controller to allow the client to send bodies with a `Content-Type` that can be deserialized using the specified serializer.
Optionally allows you to specify which views to allow by passing an array in the views parameter.
Accepts the same filters as `before_action`.
#### `allow_all_input( **filters )`
Disables input deserialization. Running `deserialize` while allowing all input will result in an error being thrown.
#### `not_acceptable_serializer( serializer )`
Replaces the serializer used to render the error page when no media type could be negotiated using the `Accept` header.
#### `unsupported_media_type_serializer( serializer )`
Adds a serializer that can be used to render the error page when the client submits a body with a `Content-Type` that was not added to the whitelist using `allow_input_serialization`.
#### `clear_unsupported_media_type_serializers!`
Clears the list of serializers used to render the error when the client supplies non-valid input.
#### `input_validation_failed_serializer( serializer )`
Adds a serializer that can be used to render the error page when input validation fails.
#### `clear_input_validation_failed_serializers!`
Clears the list of serializers used to render the error when the client supplies non-valid input.
#### `allow_api_viewer(serializer: MediaTypes::Serialization::Serializers::ApiViewer, **filter_opts)`
Enables rendering the api viewer when adding the `api_viewer=last` query parameter to the url.
#### `freeze_io!(**filter_opts)`
Registers serialization and deserialization in the controller.
This function must be called before using the controller.
### Controller usage
These functions are available during method execution in the controller.
#### `render_media( obj, serializers: nil, not_acceptable_serializer: nil, **options ) do`
Serializes an object and renders it using the appropriate content type.
Options are passed through to the controller `render` function. Allows you to specify different objects to different serializers using a block:
```ruby
render_media do
serializer BookSerializer, book
serializer BooksSerializer do
[ book ]
end
end
```
**Warning**: this block can be called multiple times when used together with recursive serializers like the API viewer.
Try to _avoid changing state_ in this block.
If you want to render with different serializers than defined in the controller you can pass an array of serializers in the `serializers` property.
If you want to override the serializer that is used to render the response when no acceptable Content-Type could be negotiated you can pass the desired serializer in the `not_acceptable_serializer` property.
This method throws a `MediaTypes::Serialization::OutputValidationFailedError` error if the output does not conform to the format defined by the configured validator.
Best practise is to return a 500 error to the client.
If no acceptable Content-Type could be negotiated the response will be rendered using the serialized defined by the class `not_acceptable_serializer` function or by the `not_acceptable_serializer` property.
Due to the way this gem is implemented it is not possible to use instance variables (`@variable`) in the `render_media` do block.
#### `deserialize( request )`
Deserializes the request body using the configured input serializers and returns the deserialized object.
Returns nil if no input body was given by the client.
This method throws a `MediaTypes::Serialization::InputValidationFailedError` error if the incoming data does not conform to the specified schema.
#### `deserialize!( request )`
Does the same as `deserialize( request )` but gives the client an error page if no input was supplied.
#### `resolve_serializer(request, identifier = nil, registration = @serialization_output_registration)`
Returns the serializer class that will handle the given request.
## Customization
The easiest way to customize the look and feel of the built in pages is to provide your own logo and background in an initializer:
```ruby
# config/initializers/serialization.rb
MediaTypes::Serialization::Serializers::CommonCSS.background = 'linear-gradient(245deg, #3a2f28 0%, #201a16 100%)'
MediaTypes::Serialization::Serializers::CommonCSS.logo_width = 12
MediaTypes::Serialization::Serializers::CommonCSS.logo_data = <<-HERE
HERE
```
## Development
After checking out the repo, run `bin/setup` to install dependencies.
Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`.
To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at [XPBytes/media_types-serialization](https://github.com/XPBytes/media_types-serialization).