active_model_serializers 0.8.3 → 0.10.0

data/docs/jsonapi/schema/schema.json

@@ -0,0 +1,366 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "JSON API Schema",
+  "description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
+  "oneOf": [
+    {
+      "$ref": "#/definitions/success"
+    },
+    {
+      "$ref": "#/definitions/failure"
+    },
+    {
+      "$ref": "#/definitions/info"
+    }
+  ],
+  
+  "definitions": {
+    "success": {
+      "type": "object",
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "$ref": "#/definitions/data"
+        },
+        "included": {
+          "description": "To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called \"compound documents\".",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/resource"
+          },
+          "uniqueItems": true
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        },
+        "links": {
+          "description": "Link members related to the primary data.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/links"
+            },
+            {
+              "$ref": "#/definitions/pagination"
+            }
+          ]
+        },
+        "jsonapi": {
+          "$ref": "#/definitions/jsonapi"
+        }
+      },
+      "additionalProperties": false
+    },
+    "failure": {
+      "type": "object",
+      "required": [
+        "errors"
+      ],
+      "properties": {
+        "errors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/error"
+          },
+          "uniqueItems": true
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        },
+        "jsonapi": {
+          "$ref": "#/definitions/jsonapi"
+        }
+      },
+      "additionalProperties": false
+    },
+    "info": {
+      "type": "object",
+      "required": [
+        "meta"
+      ],
+      "properties": {
+        "meta": {
+          "$ref": "#/definitions/meta"
+        },
+        "links": {
+          "$ref": "#/definitions/links"
+        },
+        "jsonapi": {
+          "$ref": "#/definitions/jsonapi"
+        }
+      },
+      "additionalProperties": false
+    },
+    
+    "meta": {
+      "description": "Non-standard meta-information that can not be represented as an attribute or relationship.",
+      "type": "object",
+      "additionalProperties": true
+    },
+    "data": {
+      "description": "The document's \"primary data\" is a representation of the resource or collection of resources targeted by a request.",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/resource"
+        },
+        {
+          "description": "An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/resource"
+          },
+          "uniqueItems": true
+        }
+      ]
+    },
+    "resource": {
+      "description": "\"Resource objects\" appear in a JSON API document to represent resources.",
+      "type": "object",
+      "required": [
+        "type",
+        "id"
+      ],
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "attributes": {
+          "$ref": "#/definitions/attributes"
+        },
+        "relationships": {
+          "$ref": "#/definitions/relationships"
+        },
+        "links": {
+          "$ref": "#/definitions/links"
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        }
+      },
+      "additionalProperties": false
+    },
+    
+    "links": {
+      "description": "A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.",
+      "type": "object",
+      "properties": {
+        "self": {
+          "description": "A `self` member, whose value is a URL for the relationship itself (a \"relationship URL\"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.",
+          "type": "string",
+          "format": "uri"
+        },
+        "related": {
+          "$ref": "#/definitions/link"
+        }
+      },
+      "additionalProperties": true
+    },
+    "link": {
+      "description": "A link **MUST** be represented as either: a string containing the link's URL or a link object.",
+      "oneOf": [
+        {
+          "description": "A string containing the link's URL.",
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "object",
+          "required": [
+            "href"
+          ],
+          "properties": {
+            "href": {
+              "description": "A string containing the link's URL.",
+              "type": "string",
+              "format": "uri"
+            },
+            "meta": {
+              "$ref": "#/definitions/meta"
+            }
+          }
+        }
+      ]
+    },
+
+    "attributes": {
+      "description": "Members of the attributes object (\"attributes\") represent information about the resource object in which it's defined.",
+      "type": "object",
+      "patternProperties": {
+        "^(?!relationships$|links$)\\w[-\\w_]*$": {
+          "description": "Attributes may contain any valid JSON value."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "relationships": {
+      "description": "Members of the relationships object (\"relationships\") represent references from the resource object in which it's defined to other resource objects.",
+      "type": "object",
+      "patternProperties": {
+        "^\\w[-\\w_]*$": {
+          "properties": {
+            "links": {
+              "$ref": "#/definitions/links"
+            },
+            "data": {
+              "description": "Member, whose value represents \"resource linkage\".",
+              "oneOf": [
+                {
+                  "$ref": "#/definitions/relationshipToOne"
+                },
+                {
+                  "$ref": "#/definitions/relationshipToMany"
+                }
+              ]
+            },
+            "meta": {
+              "$ref": "#/definitions/meta"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "relationshipToOne": {
+      "description": "References to other resource objects in a to-one (\"relationship\"). Relationships can be specified by including a member in a resource's links object.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/empty"
+        },
+        {
+          "$ref": "#/definitions/linkage"
+        }
+      ]
+    },
+    "relationshipToMany": {
+      "description": "An array of objects each containing \"type\" and \"id\" members for to-many relationships.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/linkage"
+      },
+      "uniqueItems": true
+    },
+    "empty": {
+      "description": "Describes an empty to-one relationship.",
+      "type": "null"
+    },
+    "linkage": {
+      "description": "The \"type\" and \"id\" to non-empty members.",
+      "type": "object",
+      "required": [
+        "type",
+        "id"
+      ],
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        }
+      },
+      "additionalProperties": false
+    },
+    "pagination": {
+      "type": "object",
+      "properties": {
+        "first": {
+          "description": "The first page of data",
+          "oneOf": [
+            { "type": "string", "format": "uri" },
+            { "type": "null" }
+          ]
+        },
+        "last": {
+          "description": "The last page of data",
+          "oneOf": [
+            { "type": "string", "format": "uri" },
+            { "type": "null" }
+          ]
+        },
+        "prev": {
+          "description": "The previous page of data",
+          "oneOf": [
+            { "type": "string", "format": "uri" },
+            { "type": "null" }
+          ]
+        },
+        "next": {
+          "description": "The next page of data",
+          "oneOf": [
+            { "type": "string", "format": "uri" },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+    
+    "jsonapi": {
+      "description": "An object describing the server's implementation",
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string"
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        }
+      },
+      "additionalProperties": false
+    },
+    
+    "error": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "description": "A unique identifier for this particular occurrence of the problem.",
+          "type": "string"
+        },
+        "links": {
+          "$ref": "#/definitions/links"
+        },
+        "status": {
+          "description": "The HTTP status code applicable to this problem, expressed as a string value.",
+          "type": "string"
+        },
+        "code": {
+          "description": "An application-specific error code, expressed as a string value.",
+          "type": "string"
+        },
+        "title": {
+          "description": "A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.",
+          "type": "string"
+        },
+        "detail": {
+          "description": "A human-readable explanation specific to this occurrence of the problem.",
+          "type": "string"
+        },
+        "source": {
+          "type": "object",
+          "properties": {
+            "pointer": {
+              "description": "A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute].",
+              "type": "string"
+            },
+            "parameter": {
+              "description": "A string indicating which query parameter caused the error.",
+              "type": "string"
+            }
+          }
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

data/docs/jsonapi/schema.md

@@ -0,0 +1,151 @@
+[Back to Guides](../README.md)
+
+[![JSON API 1.0](https://img.shields.io/badge/JSON%20API-1.0-lightgrey.svg)](http://jsonapi.org/)
+
+## JSON API Requests
+
+- [Query Parameters Spec](http://jsonapi.org/format/#query-parameters)
+
+Headers:
+
+- Request: `Accept: application/vnd.api+json`
+- Response: `Content-Type: application/vnd.api+json`
+
+### [Fetching Data](http://jsonapi.org/format/#fetching)
+
+A server MUST support fetching resource data for every URL provided as:
+
+- a `self` link as part of the top-level links object
+- a `self` link as part of a resource-level links object
+- a `related` link as part of a relationship-level links object
+
+Example supported requests
+
+- Individual resource or collection
+  - GET /articles
+  - GET /articles/1
+  - GET /articles/1/author
+- Relationships
+  - GET /articles/1/relationships/comments
+  - GET /articles/1/relationships/author
+- Optional: [Inclusion of related resources](http://jsonapi.org/format/#fetching-includes) `ActiveModel::Serializer::IncludeTree`
+  - GET /articles/1?`include`=comments
+  - GET /articles/1?`include`=comments.author
+  - GET /articles/1?`include`=author,comments.author
+  - GET /articles/1/relationships/comments?`include`=comments.author
+- Optional: [Sparse Fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets) `ActiveModel::Serializer::Fieldset`
+  - GET /articles?`include`=author&`fields`[articles]=title,body&`fields`[people]=name
+- Optional: [Sorting](http://jsonapi.org/format/#fetching-sorting)
+  - GET /people?`sort`=age
+  - GET /people?`sort`=age,author.name
+  - GET /articles?`sort`=-created,title
+- Optional: [Pagination](http://jsonapi.org/format/#fetching-pagination)
+  - GET /articles?`page`[number]=3&`page`[size]=1
+- Optional: [Filtering](http://jsonapi.org/format/#fetching-filtering)
+  - GET /comments?`filter`[post]=1
+  - GET /comments?`filter`[post]=1,2
+  - GET /comments?`filter`[post]=1,2
+
+### [CRUD Actions](http://jsonapi.org/format/#crud)
+
+### [Asynchronous Processing](http://jsonapi.org/recommendations/#asynchronous-processing)
+
+### [Bulk Operations Extension](http://jsonapi.org/extensions/bulk/)
+
+## JSON API Document Schema
+
+| JSON API object       | JSON API properties                                                                                | Required | ActiveModelSerializers representation |
+|-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
+| schema                | oneOf (success, failure, info)                                                                     |          |
+| success               | data, included, meta, links, jsonapi                                                               |          | AM::SerializableResource
+| success.meta          | meta                                                                                               |          | AMS::Adapter::Base#meta
+| success.included      | UniqueArray(resource)                                                                              |          | AMS::Adapter::JsonApi#serializable_hash_for_collection
+| success.data          | data                                                                                               |          |
+| success.links         | allOf (links, pagination)                                                                          |          | AMS::Adapter::JsonApi#links_for
+| success.jsonapi       | jsonapi                                                                                            |          |
+| failure               | errors, meta, jsonapi                                                                              | errors   | AMS::Adapter::JsonApi#failure_document, #1004
+| failure.errors        | UniqueArray(error)                                                                                 |          | AM::S::ErrorSerializer, #1004
+| meta                  | Object                                                                                             |          | 
+| data                  | oneOf (resource, UniqueArray(resource))                                                            |          | AMS::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
+| resource              | String(type), String(id),<br>attributes, relationships,<br>links, meta                                   | type, id | AM::S::Adapter::JsonApi#primary_data_for
+| links                 | Uri(self), Link(related)                                                                           |          | #1028, #1246, #1282
+| link                  | oneOf (linkString, linkObject)                                                                     |          |
+| link.linkString       | Uri                                                                                                |          |
+| link.linkObject       | Uri(href), meta                                                                                    | href     |
+| attributes            | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON                      |          | AM::Serializer#attributes, AMS::Adapter::JsonApi#resource_object_for
+| relationships         | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta                              |          | AMS::Adapter::JsonApi#relationships_for
+| relationships.data    | oneOf (relationshipToOne, relationshipToMany)                                                      |          | AMS::Adapter::JsonApi#resource_identifier_for
+| relationshipToOne     | anyOf(empty, linkage)                                                                              |          |
+| relationshipToMany    | UniqueArray(linkage)                                                                               |          |
+| empty                 | null                                                                                               |          |
+| linkage               | String(type), String(id), meta                                                                     | type, id | AMS::Adapter::JsonApi#primary_data_for
+| pagination            | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next)                            |          | AMS::Adapter::JsonApi::PaginationLinks#serializable_hash
+| pagination.pageObject | oneOf(Uri, null)                                                                                   |          |
+| jsonapi               | String(version), meta                                                                              |          | AMS::Adapter::JsonApi::Jsonapi#as_json
+| error                 | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta |          | AM::S::ErrorSerializer, AMS::Adapter::JsonApi::Error.resource_errors
+| error.source          | String(pointer), String(parameter)                                                                 |          | AMS::Adapter::JsonApi::Error.error_source
+| pointer               | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901)                                        |          | AMS::JsonPointer
+
+
+The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
+
+### Success Document
+- [ ] success
+  - [ ] data: `"$ref": "#/definitions/data"`
+  - [ ] included: array of unique items of type `"$ref": "#/definitions/resource"`
+  - [ ] meta: `"$ref": "#/definitions/meta"`
+  - [ ] links:
+    - [ ] link: `"$ref": "#/definitions/links"`
+    - [ ] pagination: ` "$ref": "#/definitions/pagination"`
+  - [ ] jsonapi: ` "$ref": "#/definitions/jsonapi"`
+
+### Failure Document
+
+- [ ] failure
+  - [x] errors: array of unique items of type ` "$ref": "#/definitions/error"`
+  - [ ] meta:  `"$ref": "#/definitions/meta"`
+  - [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
+
+### Info Document
+
+- [ ] info
+  - [ ] meta: `"$ref": "#/definitions/meta"`
+  - [ ] links: `"$ref": "#/definitions/links"`
+  - [ ] jsonapi: ` "$ref": "#/definitions/jsonapi"`
+
+### Definitions
+
+- [ ] definitions:
+  - [ ] meta
+  - [ ] data: oneOf (resource, array of unique resources)
+  - [ ] resource
+    - [ ] attributes
+    - [ ] relationships
+      - [ ] relationshipToOne
+        - [ ] empty
+        - [ ] linkage
+          - [ ] meta
+      - [ ] relationshipToMany
+        - [ ] linkage
+          - [ ] meta
+    - [ ] links
+    - [ ] meta
+  - [ ] links
+    - [ ] link
+      - [ ] uri
+      - [ ] href, meta
+  - [ ] pagination
+  - [ ] jsonapi
+    - [ ] meta
+  - [ ] error
+    - [ ] id: a unique identifier for this particular occurrence of the problem.
+    - [ ] links: a links object containing the following members:
+      - [ ] about: a link that leads to further details about this particular occurrence of the problem.
+    - [ ] status: the HTTP status code applicable to this problem, expressed as a string value.
+    - [ ] code: an application-specific error code, expressed as a string value.
+    - [ ] title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
+    - [x] detail: a human-readable explanation specific to this occurrence of the problem.
+    - [x] source: an object containing references to the source of the error, optionally including any of the following members:
+      -  [x] pointer: a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
+      -  [x] parameter: a string indicating which query parameter caused the error.
+    - [ ] meta: a meta object containing non-standard meta-information about the error.

data/docs/rfcs/0000-namespace.md

@@ -0,0 +1,106 @@
+- Start Date: (2015-10-29)
+- RFC PR: https://github.com/rails-api/active_model_serializers/pull/1310
+- ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/1298
+
+# Summary
+
+Provide a consistent API for the user of the AMS.
+
+# Motivation
+
+The actual public API is defined under `ActiveModelSerializers`,
+`ActiveModel::Serializer` and `ActiveModel`.
+
+At the `ActiveModel::Serializer` we have:
+
+- `ActiveModel::Serializer.config`
+- `ActiveModel::Serializer`
+
+At the `ActiveModelSerializers` we have:
+
+- `ActiveModelSerializers::Model`
+- `ActiveModelSerializers.logger`
+
+At `ActiveModel` we have:
+
+- `ActiveModel::SerializableResource`
+
+The idea here is to provide a single namespace `ActiveModelSerializers` to the user.
+Following the same idea we have on other gems like
+[Devise](https://github.com/plataformatec/devise/blob/e9c82472ffe7c43a448945f77e034a0e47dde0bb/lib/devise.rb),
+[Refile](https://github.com/refile/refile/blob/6b24c293d044862dafbf1bfa4606672a64903aa2/lib/refile.rb) and
+[Active Job](https://github.com/rails/rails/blob/30bacc26f8f258b39e12f63fe52389a968d9c1ea/activejob/lib/active_job.rb)
+for example.
+
+This way we are clarifing the boundaries of
+[ActiveModelSerializers and Rails](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md#prehistory)
+and make clear that the `ActiveModel::Serializer` class is no longer the primary
+behavior of the ActiveModelSerializers.
+
+# Detailed design
+
+## New classes and modules organization
+
+Since this will be a big change we can do this on baby steps, read small pull requests. A
+possible approach is:
+
+- All new code will be in `lib/active_model_serializers/` using
+  the module namespace `ActiveModelSerializers`.
+- Move all content under `ActiveModel::Serializer` to be under
+  `ActiveModelSerializers`, the adapter is on this steps;
+- Move all content under `ActiveModel` to be under `ActiveModelSerializers`,
+  the `SerializableResource` is on this step;
+- Change all public API that doesn't make sense, keeping in mind only to keep
+  this in the same namespace
+- Update the README;
+- Update the docs;
+
+The following table represents the current and the desired classes and modules
+at the first moment.
+
+| Current                                                | Desired                                          | Notes              |
+|--------------------------------------------------------|--------------------------------------------------|--------------------|
+| `ActiveModelSerializers` and `ActiveModel::Serializer` | `ActiveModelSerializers`                         | The main namespace |
+| `ActiveModelSerializers.logger`                        | `ActiveModelSerializers.logger`                  ||
+| `ActiveModelSerializers::Model`                        | `ActiveModelSerializers::Model`                  ||
+| `ActiveModel::SerializableResource`                    | `ActiveModelSerializers::SerializableResource`   ||
+| `ActiveModel::Serializer`                              | `ActiveModelSerializers::Serializer`             | The name can be discussed in a future pull request. For example, we can rename this to `Resource` [following this idea](https://github.com/rails-api/active_model_serializers/pull/1301/files#r42963185) more info about naming in the next section|
+| `ActiveModel::Serializer.config`                       | `ActiveModelSerializers.config`                ||
+
+## Renaming of class and modules
+
+When moving some content to the new namespace we can find some names that does
+not make much sense like `ActiveModel::Serializer::Adapter::JsonApi`.
+Discussion of renaming existing classes / modules and JsonApi objects will
+happen in separate pull requests, and issues, and in the google doc
+https://docs.google.com/document/d/1rcrJr0sVcazY2Opd_6Kmv1iIwuHbI84s1P_NzFn-05c/edit?usp=sharing
+
+Some of names already have a definition.
+
+- Adapters get their own namespace under ActiveModelSerializers. E.g
+  `ActiveModelSerializers::Adapter`
+- Serializers get their own namespace under ActiveModelSerializers. E.g
+  `ActiveModelSerializers::Serializer`
+
+## Keeping compatibility
+
+All moved classes or modules be aliased to their old name and location with
+deprecation warnings, such as
+[was done for CollectionSerializer](https://github.com/rails-api/active_model_serializers/pull/1251).
+
+# Drawbacks
+
+This will be a breaking change, so all users serializers will be broken after a
+major bump.
+All pull requests will need to rebase since the architeture will change a lot.
+
+# Alternatives
+
+We can keep the way it is, and keep in mind to not add another namespace as a
+public API.
+
+# Unresolved questions
+
+What is the better class name to be used to the class that will be inherited at
+the creation of a serializer. This can be discussed in other RFC or directly via
+pull request.

data/docs/rfcs/template.md

@@ -0,0 +1,15 @@
+- Start Date: (YYYY-MM-DD)
+- RFC PR: https://github.com/rails-api/active_model_serializers/pull/dddd
+- ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/dddd
+
+# Summary
+
+# Motivation
+
+# Detailed design
+
+# Drawbacks
+
+# Alternatives
+
+# Unresolved questions