MediaTypes::Serialization

respond_to on steroids. Add HATEOAS compatible serialization and deserialization to your Rails projects.

Installation

Add this line to your application's Gemfile:

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 and the other way around.

Creating a serializer

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:

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 using the Accept header:

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:

class BookController < ApplicationController
  def show
    @book = Book.new

    # Use view corresponding to the controller
  end
end

You can add a json representation as follows:

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:

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.

Versioning

To help with supporting older versions, serializers have a DSL to construct json objects:

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

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 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:

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:

BookSerializer.serialize(book, BookValidator.version(3), context: controller)
# header = Link: <https://example.org/>; 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 (index based collections)

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 (view: nil) of the given version.

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

BookSerializer.serialize([book], BookValidator.view(:index).version(3), context: controller)
# header = Link: <https://example.org/index>; rel="self"
# => {
#      "books": {
#        "_links": {
#          "self": { "href": "https://example.org" }
#        },
#        "_index": [
#          { "href": "https://example.org" }
#        ]
#      }
#    }

How to validate?

The index dsl does not exist in the validation gem. This is how you validate indices:

class BookValidator
  include MediaTypes::Dsl

  def self.organisation
    'acme'
  end

  use_name 'book'

  validations do
    view :index do
      version 3 do
        attribute :books do
          link :self

          collection :_index, allow_empty: true do
            attribute :href, String
          end
        end
      end
    end
  end
end

If the :self link contains more attributes, they will show up here too.

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), isbn: obj.isbn 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

class BookValidator
  include MediaTypes::Dsl

  def self.organisation
    'acme'
  end

  use_name 'book'

  validations do
    view :index do
      version 3 do
        attribute :books do
          link :self

          collection :_index, allow_empty: true do
            attribute :href, String
            attribute :isbn, AllowNil(String)
          end
        end
      end
    end
  end
end

Collections (embedding collections)

A collection inlines the member objects. The collection method automatically generates it based on the default view of the same version.

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

BookSerializer.serialize([book], BookValidator.view(:collection).version(3), context: controller)
# header = Link: <https://example.org/collection>; rel="self"
# => {
#      "books": {
#        "_links": {
#          "self": { "href": "https://example.org" }
#        },
#        "_embedded": [
#          {
#            "_links": {
#              "self": { "href": "https://example.org" }
#            },
#            "title": "Everything, abridged",
#            "description": "Mu"
#          }
#        ]
#      }
#    }

The collection dsl is not the same as the one in the validation gem. This is how you could validate collections:

class BookValidator
  include MediaTypes::Dsl

  def self.organisation
    'acme'
  end

  use_name 'book'

  validations do
    view :collection do
      version 3 do
        attribute :books do
          link :self

          collection :_embedded, allow_empty: true do
            link :self

            attribute :title, String
            attribute :description, AllowNil(String)
          end
        end
      end
    end
  end
end

Input deserialization

You can mark a media type as something that's allowed to be sent along with a PUT request as follows:

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 book
  end

  def create
    json = deserialize(request) # does validation for us
    puts json
  end
end

If you use ActiveRecord you might want to convert the verified json data during deserialization:

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 book
  end

  def create
    book = deserialize(request)
    book.save!

    render_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:

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:

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 practice as this makes it hard to add new fields or remove old ones, this library has support for migrating away:

class BookSerializer < MediaTypes::Serialization::Base
  validator BookValidator

  # applicaton/vnd.acme.book.v3+json
  # applicaton/vnd.acme.book.v2+json
  # applicaton/vnd.acme.book.v1+json
  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

  # applicaton/vnd.acme.book+json
  output version: nil do |obj, version, context|
    attribute :book do
      attribute :title, obj.title
    end
  end
  output_alias 'application/json' # maps application/json to to applicaton/vnd.acme.book+json

  # applicaton/vnd.acme.book.v3.create+json
  # applicaton/vnd.acme.book.v2.create+json
  # applicaton/vnd.acme.book.v1.create+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

  # applicaton/vnd.acme.book.create+json
  input view: :create, version: nil do |json, version, context|
    book = Book.new
    book.title = json['book']['title']
    book.description = 'Not available'

    # 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.create+json

Validation will be done using the remapped validator. Aliasses map to version nil. 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.

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 book
  end

  def create
    json = deserialize(request) # does validation for us
    puts json
  end
end

You can also output custom HTML:

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 media type. You can catch and transform application errors by adding an output_error call before freeze_io!:

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 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_detail(description, lang:) function.

Custom attributes can be added using the problem_output.attribute(name, value) function.

MediaTypes: :gem: Library to create media type validators.

API

Serializer class 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.<organisation>.<name>.

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.

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. nil is allowed for unversioned. 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:, suffix: ) do |obj, version, context|`

This has the same behavior as output but should return a string instead of an object. Output is not validated. By default, input_raw is expected to not be JSON. Override suffix with :json if it is JSON.

`output_alias( media_type_identifier, view:, hide_variant: false, suffix: '~' )`

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. By default, suffix is :json if media_type_identifier is a JSON type.

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, suffix: '~' )`

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. By default, suffix is :json if media_type_identifier is a JSON type.

`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.

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:, suffix: nil ) do |bytes, version, context|`

This has the same behavior as input but takes in raw data. Input is not validated. By default, input_raw is expected to not be JSON. Override suffix with :json if it is JSON.

`input_alias( media_type_identifier, view:, suffix: '~' )`

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. By default, suffix is :json if media_type_identifier is a JSON type.

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:, suffix: '~' )`

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. By default, suffix is :json if media_type_identifier is a JSON type.

`disable_wildcards`

Disables registering wildcard media types.

Serializer output 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.