media_types-serialization 0.8.1 → 1.0.1

data/LICENSE.txt

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2019 Derk-Jan Karrenbeld
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2019 Derk-Jan Karrenbeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/media_types-serialization.svg)](https://badge.fury.io/rb/media_types-serialization)
 [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
 
-Add media types supported serialization using your favourite serializer
+`respond_to` on steroids. Add versioned serialization and deserialization to your rails projects.
 
 ## Installation
 
@@ -21,269 +21,513 @@ And then execute:
 Or install it yourself as:
 
     $ gem install media_types-serialization
-    
-If you have not done this before, and you're using `rails`, install the necessary parts using:
 
-```bash
-rails g media_types:serialization:api_viewer
+## 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
 ```
 
-This will:
+To convert a ruby object to a json representation:
 
-- Add the default `html_wrapper` layout which is an API Viewer used as fallback or the `.api_viewer` format
-- Add the default `template_controller` which allows the API Viewer to post templated links
-- Add the `route` for these templated link forms
-- Add an initializer that registers the `media` renderer and `api_viewer` media type
+```ruby
+class Book
+  attr_accessor :title
+end
 
-## Usage
+book = Book.new
+book.title = 'Everything, abridged'
 
-In order to use media type serialization you only need to do 2 things:
+BookSerializer.serialize(book, 'vnd.acme.book.v1+json', context: nil)
+# => { "book": { "title": "Everything, abridged" } }
+```
 
-### Serializer
+### 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):
 
-Add a serializer that can serialize a certain media type. The `to_hash` function will be called _explicitly_ in your
-controller, so you can always use your own, favourite serializer here to do the hefty work. This gem does provide some
-easy tools, usually enough to do most serialization.
-  
 ```ruby
-class Book < ApplicationRecord
-  class Serializer < MediaTypes::Serialization::Base
-    serializes_media_type MyNamespace::MediaTypes::Book
-    
-    def fields
-      if current_media_type.create?
-        return %i[name author]
-      end
-    
-     %i[name author updated_at views]
-    end
+require 'media_types'
+
+class BookValidator
+  include MediaTypes::Dsl
 
-    def to_hash
-      extract(serializable, fields).tap do |result|
-        result[:_links] = extract_links unless current_media_type.create?
+  def self.organisation
+    'acme'
+  end
+
+  use_name 'book'
+
+  validations do
+    version 1 do
+      attribute :book do
+        attribute :title, String
       end
     end
+  end
+end
 
-    alias to_h to_hash
-    
-    protected
-    
-    def extract_self
-      # A serializer gets the controller as context
-      { href: context.api_book_url(serializable) }
-    end
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
 
-    def extract_links
-      { 
-        'self': extract_self,
-        'signatures': { href: context.api_book_signatures_url(serializable) }
+  # 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).
+
+### 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.
+
+### 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://en.wikipedia.org/wiki/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:
+
+```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
 ```
-By default, The passed in `MediaType` gets converted into a constructable (via `to_constructable`) and invoked with the
-current `view` (e.g. `create`, `index`, `collection` or ` `). This means that by default it will be able to serialize 
-the latest version you `MediaType` is reporting. The best way to supply your media type is via the [`media_types`](https://github.com/SleeplessByte/media-types-ruby) gem.
 
-#### Multiple suffixes, one serializer
+This returns the following response:
 
-By default, the media renderer will automatically detect and inject the following:
-- suffix `+json` if you define `to_json`
-- suffix `+xml` if you define `to_xml`
-- type `text/html` if you define `to_html`
+```ruby
+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"
+#      }
+#    }
+```
 
-If you do _not_ define these methods, only the `default` suffix / type will be used, `accepts_html` for the `text/html` 
-content-type.
+### Collections
 
-If you don't define `to_html`, but try to make a serializer output `html`, it will be rendered in the layout at: 
-`serializers/wrapper/html_wrapper.html.erb` (or any other templating extension).
+There are convenience methods for serializing arrays of objects based on a template.
 
-#### Migrations (versions)
+#### Indexes
 
-If the serializer can serialize multiple _versions_, you can supply them through `additional_versions: [2, 3]`. A way to
-handle this is via backward migrations, meaning you'll migrate from the current version back to an older version.
+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 Book < ApplicationRecord
-  class BasicSerializer < MediaTypes::Serialization::Base
-  
-    # Maybe it's currently at version 2, so tell the base that this also serializes version 1
-    # You can also use a range to_a: (1...4).to_a
-    # 
-    serializes_media_type MyNamespace::MediaTypes::Book, additional_versions: [1]
-    
-    def to_hash
-      # This enables migrations right when it's being serialized
-      # 
-      migrate do
-        extract(serializable, fields).tap do |result|
-          result[:_links] = extract_links unless current_media_type.create?
-        end
-      end
+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: <https://example.org/index>; 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
   
-    # This defines migrations. You can use classes, commands or anything else to execute this code
-    # but inline migrations work fine if you don't have a lot of them. 
-    backward_migrations do
-    
-      # This is called if the version requested is 1 _or_ lower. This means you can compose your migrations. The 
-      # migrations with a _lower_ version than the requested version are NOT executed.
-      version 1 do |result|
-        result.tap do |r|
-          if r.key?(:views)
-            r[:views_count] = r.delete(:views)
-          end
-        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
 ```
 
-### Controller
+```ruby
+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"
+#          }
+#        ]
+#      }
+#    }
+```
+
+### Input deserialization
 
-In your base controller, or wherever you'd like, include the `MediaTypes::Serialization` concern. In the controller that
-uses the serialization, you need to explicitly `accept` it if you want to use the built-in lookups.
+You can mark a media type as something that's allowed to be sent along with a PUT request as follows:
 
 ```ruby
-require 'media_types/serialization'
-require 'media_types/serialization/renderer/register'
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
 
-class ApiController < ActionController::API
-  include MediaTypes::Serialization
+  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 version: 3
 end
 
-class BookController < ApiController
+class BookController < ActionController::API
+  include MediaTypes::Serialization
 
-  accept_serialization(Book::BasicSerializer, accept_html: false, only: %i[show])
-  accept_html(Book::CoverHtmlSerializer, only: %i[show])
-  freeze_accepted_media!
+  allow_output_serializer(BookSerializer, only: %i[show])
+  allow_input_serializer(BookSerializer, only: %i[create])
+  freeze_io!
       
   def show 
-    # If you do NOT pass in the content_type, it will re-use the current content_type of the response if set or
-    # use the default content type of the serializer. This is fine if you only output one Content-Type in the
-    # action, but not if you are relying on content-negotiation. 
-    
-    render media: serialize_media(@book), content_type: request.format.to_s
+    book = Book.new
+    book.title = 'Everything, abridged'
+
+    render media: serialize_media(book), content_type: request.format.to_s
+  end
+
+  def create
+    json = deserialize(request, context: self) # does validation for us
+    puts json
   end
 end
 ```
 
-If you have normalized your resources (e.g. into `@resource`), you can add a `render_media` method to your
-`BaseController` and render resources like so:
+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 ApiController < ActionController::API
-  def render_media(**opts)
-    render media: serialize_media(@resource), content_type: request.format.to_s, **opts
+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
-```
 
-And then call `render_media` whenever you're ready to render.
+class BookController < ActionController::API
+  include MediaTypes::Serialization
 
-### HTML output
+  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'
 
-You can define HTML outputs for example by creating a serializer that accepts `text/html`. At this moment, there may
-only be one (1) active `text/html` serializer for each action; a single controller can have multiple registered, but 
-never for the same preconditions in `before_action` (because how else would it know which one to pick?).
+    render media: serialize_media(book), content_type: request.format.to_s
+  end
 
-Use the `render` method to generate your HTML:
-```ruby
-class Book::CoverHtmlSerializer < MediaTypes::Serialization::Base
-  # Tell the serializer that this accepts HTML, but this is also signaled by `to_html`
-  serializes_html
-  
-  def to_html
-    ApplicationController.render(
-      'serializers/book/cover',
-      assigns: {
-        title: extract_title,
-        image: resolve_file_url(covers.first&.version_url('small')),
-        description: extract_description,
-        language_links: language_links,
-      },
-      layout: false
-    )
+  def create
+    book = deserialize(request, context: self)
+    book.save!
+
+    render media: serialize_media(book), content_type request.format.to_s
   end
-  
-  # Naturally you have to define extract_title, etc etc 
 end
 ```
 
-You can change the default `wrapper` / `to_html` implementation by setting:
+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
-::MediaTypes::Serialization.html_wrapper_layout = '/path/to/wrapper/layout'
+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
 ```
 
-### API viewer
+### Raw input
 
-There is a special media type exposed by this gem at `::MediaTypes::Serialization::MEDIA_TYPE_API_VIEWER`. If you're
-using `rails` you'll want to register it. You can do so manually, or by `require`ing:
+You can do the same with input:
 
 ```ruby
-require 'media_types/serialization/media_type/register'
+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
 ```
 
-If you do so, the `.api_viewer` format becomes available for all actions that call into `render media:`.
+### Remapping media type identifiers
 
-You can change the default `wrapper` implementation by setting:
+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
-::MediaTypes::Serialization.api_viewer_layout = '/path/to/wrapper/layout'
+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
 ```
 
-### Wrapping output
+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.
 
-By convention, `index` views are wrapped in `_index: [items]`, `collection` views are wrapped in `_embedded: [items]`
-and `create` / no views are wrapped in `[ROOT_KEY]: item`. This is currently only enabled for `to_json` serialization
-but planned for `xml` as well.
+To enable the API viewer, use: `allow_api_viewer` in the controller.
 
-This behaviour can not be turned of as of writing. However, you may _overwrite_ this behaviour via:
+```ruby
+class BookController < ActionController::API
+  include MediaTypes::Serialization
 
-- `self.root_key(view:)`: to define the root key for a specific `view`
-- `self.wrap(serializer, view: nil)`: to define the wrapper for a specific `view` and/or `serializer`. For example, if
-  you never want to wrap anything, you could define:
-  ```ruby
-  def self.wrap(serializer, view: nil)
-    serializer
+  allow_api_viewer
+  
+  allow_output_serializer(MediaTypes::ApiViewer)
+
+  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), content_type: request.format.to_s
   end
-  ```
 
-### Link header
+  def create
+    json = deserialize(request, context: self) # does validation for us
+    puts json
+  end
+end
+```
 
-You can use `to_link_header` to generate a header value for the `Link` header.
+You can also output custom HTML:
 
 ```ruby
-entries = @last_media_serializer.to_link_header
-if entries.present?
-  response.header[HEADER_LINK] = entries
+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
 ```
 
-If you want the link header to be different from the `_links`, you can implement `header_links(view:)` next to 
-`extract_links(view:)`. This will be called by the `to_link_header` function.
+#### Errors
 
-### Validation
-If you only have `json`/`xml`/structured data responses and you want to use [`media_types-validation`](https://github.com/XPBytes/media_types-validation) in conjunction with this gem, you can create a concern or add the following two functions to your base controller:
+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
-def render_media(resource = @resource, **opts)
-  serializer = serialize_media(resource)
-  render media: serializer, content_type: request.format.to_s, **opts
-  validate_media(serializer)
-end
+class BookController < ActionController::API
+  include MediaTypes::Serialization
+
+  output_error CanCan::AccessDenied do |p, error|
+    p.title 'You do not have enough permissions to perform this action.', lang: 'en'
+    p.title 'Je hebt geen toestemming om deze actie uit te voeren.', lang: 'nl-NL'
+
+    p.status_code :forbidden
+  end
+
+  freeze_io!
 
-def validate_media(serializer = @last_media_serializer)
-  media_type = serializer.current_media_type
-  return true unless media_type && response_body
-  validate_json_with_media_type(serializer.to_hash, media_type: media_type)
+  # ...   
 end
 ```
 
-As long as the serializer has a `to_json` or `to_hash`, this will work -- but also means that the data will always be validate _as if_ it were json. This covers most use cases.
+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: http://docs.delftsolutions.nl/wiki/Error
+If you want to override this url you can use the `p.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 `p.override_details(description, lang:)` function.
+
+Custom attributes can be added using the `p.attribute(name, value)` function.
 
 ### Related
 
@@ -291,6 +535,229 @@ As long as the serializer has a `to_json` or `to_hash`, this will work -- but al
 - [`MediaTypes::Deserialization`](https://github.com/XPBytes/media_types-deserialization): :cyclone: Add media types supported deserialization using your favourite parser, and media type validation.
 - [`MediaTypes::Validation`](https://github.com/XPBytes/media_types-validation): :heavy_exclamation_mark: Response validations according to a media-type
 
+## 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.<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](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: )`
+
+Defines a legacy mapping. This will make the deserializer parse the media type `media_type_identifier` as if it was version 1 of the specified view. If view is undefined it will use the output serializer without a view defined.
+
+#### `output_alias_optional( media_type_identifier, view: )`
+
+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.
+
+#### `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 1 of the specified view. If view is undefined it will use the input serializer without a view defined.
+
+#### `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_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!`
+
+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
+<svg height="150" width="500">
+  <ellipse cx="240" cy="100" rx="220" ry="30" style="fill:purple" />
+  <ellipse cx="220" cy="70" rx="190" ry="20" style="fill:lime" />
+  <ellipse cx="210" cy="45" rx="170" ry="15" style="fill:yellow" />
+</svg>
+HERE
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can