Merge pull request #1004 from bf4/json_api_errors

JSON API Errors (Initial implementation and roadmap for full feature-set)

Author: NullVoxPopuli

CHANGELOG.md

@@ -3,6 +3,9 @@
 Breaking changes:
 
 Features:
+- [#1004](https://github.com/rails-api/active_model_serializers/pull/1004) JSON API errors object implementation.
+  - Only implements `detail` and `source` as derived from `ActiveModel::Error`
+  - Provides checklist of remaining questions and remaining parts of the spec.
 - [#1515](https://github.com/rails-api/active_model_serializers/pull/1515) Adds support for symbols to the
   `ActiveModel::Serializer.type` method. (@groyoh)
 - [#1504](https://github.com/rails-api/active_model_serializers/pull/1504) Adds the changes missing from #1454

docs/README.md

@@ -14,7 +14,9 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [Caching](general/caching.md)
 - [Logging](general/logging.md)
 - [Instrumentation](general/instrumentation.md)
-- [JSON API Schema](jsonapi/schema.md)
+- JSON API
+  - [Schema](jsonapi/schema.md)
+  - [Errors](jsonapi/errors.md)
 - [ARCHITECTURE](ARCHITECTURE.md)
 
 ## How to

docs/jsonapi/errors.md

@@ -0,0 +1,56 @@
+[Back to Guides](../README.md)
+
+# [JSON API Errors](http://jsonapi.org/format/#errors)
+
+Rendering error documents requires specifying the error serializer(s):
+
+- Serializer:
+  - For a single resource: `serializer: ActiveModel::Serializer::ErrorSerializer`.
+  - For a collection: `serializer: ActiveModel::Serializer::ErrorsSerializer`, `each_serializer: ActiveModel::Serializer::ErrorSerializer`.
+
+The resource **MUST** have a non-empty associated `#errors` object.
+The `errors` object must have a `#messages` method that returns a hash of error name to array of
+descriptions.
+
+## Use in controllers
+
+```ruby
+resource = Profile.new(name: 'Name 1',
+                       description: 'Description 1',
+                       comments: 'Comments 1')
+resource.errors.add(:name, 'cannot be nil')
+resource.errors.add(:name, 'must be longer')
+resource.errors.add(:id, 'must be a uuid')
+
+render json: resource, status: 422, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
+# #=>
+#  { :errors =>
+#    [
+#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'cannot be nil' },
+#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be longer' },
+#      { :source => { :pointer => '/data/attributes/id' }, :detail => 'must be a uuid' }
+#    ]
+#  }.to_json
+```
+
+## Direct error document generation
+
+```ruby
+options = nil
+resource = ModelWithErrors.new
+resource.errors.add(:name, 'must be awesome')
+
+serializable_resource = ActiveModel::SerializableResource.new(
+  resource, {
+    serializer: ActiveModel::Serializer::ErrorSerializer,
+    adapter: :json_api
+  })
+serializable_resource.as_json(options)
+# #=>
+# {
+#   :errors =>
+#     [
+#       { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be awesome' }
+#     ]
+# }
+```

docs/jsonapi/schema.md

@@ -58,33 +58,33 @@ Example supported requests
 |-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
 | schema                | oneOf (success, failure, info)                                                                     |          |
 | success               | data, included, meta, links, jsonapi                                                               |          | AM::SerializableResource
-| success.meta          | meta                                                                                               |          | AM::S::Adapter::Base#meta
-| success.included      | UniqueArray(resource)                                                                              |          | AM::S::Adapter::JsonApi#serializable_hash_for_collection
+| 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)                                                                          |          | AM::S::Adapter::JsonApi#links_for
+| success.links         | allOf (links, pagination)                                                                          |          | AMS::Adapter::JsonApi#links_for
 | success.jsonapi       | jsonapi                                                                                            |          |
-| failure               | errors, meta, jsonapi                                                                              | errors   |
-| failure.errors        | UniqueArray(error)                                                                                 |          | #1004
-| meta                  | Object                                                                                             |          |
-| data                  | oneOf (resource, UniqueArray(resource))                                                            |          | AM::S::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
+| 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, AM::S::Adapter::JsonApi#resource_object_for
-| relationships         | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta                              |          | AM::S::Adapter::JsonApi#relationships_for
-| relationships.data    | oneOf (relationshipToOne, relationshipToMany)                                                      |          | AM::S::Adapter::JsonApi#resource_identifier_for
+| 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 | AM::S::Adapter::JsonApi#primary_data_for
-| pagination            | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next)                            |          | AM::S::Adapter::JsonApi::PaginationLinks#serializable_hash
+| 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                                                                              |          | AM::S::Adapter::JsonApi::ApiObjects::JsonApi
-| error                 | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta |          |
-| error.source          | String(pointer), String(parameter)                                                                 |          |
-| pointer               | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901)                                        |          |
+| jsonapi               | String(version), meta                                                                              |          | AMS::Adapter::JsonApi::ApiObjects::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.
@@ -102,7 +102,7 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
 ### Failure Document
 
 - [ ] failure
-  - [ ] errors: array of unique items of type ` "$ref": "#/definitions/error"`
+  - [x] errors: array of unique items of type ` "$ref": "#/definitions/error"`
   - [ ] meta:  `"$ref": "#/definitions/meta"`
   - [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
 
@@ -137,4 +137,15 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
   - [ ] pagination
   - [ ] jsonapi
     - [ ] meta
-  - [ ] error: id, links, status, code, title: detail: source [{pointer, type}, {parameter: {description, type}], 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.

lib/active_model/serializer.rb

@@ -1,6 +1,8 @@
 require 'thread_safe'
 require 'active_model/serializer/collection_serializer'
 require 'active_model/serializer/array_serializer'
+require 'active_model/serializer/error_serializer'
+require 'active_model/serializer/errors_serializer'
 require 'active_model/serializer/include_tree'
 require 'active_model/serializer/associations'
 require 'active_model/serializer/attributes'
@@ -116,6 +118,10 @@ def initialize(object, options = {})
       end
     end
 
+    def success?
+      true
+    end
+
     # Used by adapter as resource root.
     def json_key
       root || object.class.model_name.to_s.underscore

lib/active_model/serializer/adapter/json_api/api_objects/relationship.rb

@@ -4,6 +4,10 @@ module Adapter
       class JsonApi
         module ApiObjects
           class Relationship
+            # {http://jsonapi.org/format/#document-resource-object-related-resource-links Document Resource Object Related Resource Links}
+            # {http://jsonapi.org/format/#document-links Document Links}
+            # {http://jsonapi.org/format/#document-resource-object-linkage Document Resource Relationship Linkage}
+            # {http://jsonapi.org/format/#document-meta Docment Meta}
             def initialize(parent_serializer, serializer, options = {}, links = {}, meta = nil)
               @object = parent_serializer.object
               @scope = parent_serializer.scope

lib/active_model/serializer/adapter/json_api/api_objects/resource_identifier.rb

@@ -4,6 +4,7 @@ module Adapter
       class JsonApi
         module ApiObjects
           class ResourceIdentifier
+            # {http://jsonapi.org/format/#document-resource-identifier-objects Resource Identifier Objects}
             def initialize(serializer)
               @id = id_for(serializer)
               @type = type_for(serializer)

lib/active_model/serializer/collection_serializer.rb

@@ -22,6 +22,10 @@ def initialize(resources, options = {})
         end
       end
 
+      def success?
+        true
+      end
+
       def json_key
         root || derived_root
       end

lib/active_model/serializer/error_serializer.rb

@@ -0,0 +1,10 @@
+class ActiveModel::Serializer::ErrorSerializer < ActiveModel::Serializer
+  # @return [Hash<field_name,Array<error_message>>]
+  def as_json
+    object.errors.messages
+  end
+
+  def success?
+    false
+  end
+end

lib/active_model/serializer/errors_serializer.rb

@@ -0,0 +1,27 @@
+require 'active_model/serializer/error_serializer'
+class ActiveModel::Serializer::ErrorsSerializer
+  include Enumerable
+  delegate :each, to: :@serializers
+  attr_reader :object, :root
+
+  def initialize(resources, options = {})
+    @root = options[:root]
+    @object = resources
+    @serializers = resources.map do |resource|
+      serializer_class = options.fetch(:serializer) { ActiveModel::Serializer::ErrorSerializer }
+      serializer_class.new(resource, options.except(:serializer))
+    end
+  end
+
+  def success?
+    false
+  end
+
+  def json_key
+    nil
+  end
+
+  protected
+
+  attr_reader :serializers
+end