active_model_serializers: Serializing errors

This is what I use in my app:

      render json: model, status: 422, serializer: ActiveModel::Serializer::ErrorSerializer

Wanted to copy the PR description from #1004 to track further changes / remaining TODOs

Courtesy of @bf4

Usage

Requires explicit passing of Error serializer

# POST /api/{plural_resource_name}
def create  
  set_resource(resource_class.new(resource_params))

  if get_resource.save
    render :show, status: :created, adapter: :json_api
  else
    render json: get_resource.errors, status: :unprocessable_entity, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
  end
end

PR TODOS:

• DOCS
  • Usage and requirements jsonapi/errors.md
  • data and errors cannot co-exist. http://jsonapi.org/format/#document-top-level ref
    • requests are transactional, so any part that succeeds needs to be rolled back if any part fails. http://jsonapi.org/format/#crud ref
  • examples http://jsonapi.org/examples/#error-objects ref
• changelog

Error object:

Serializing errors is different from resources.

• Errors may be an instance of ActiveModel::Error, which we’d want to call model.errors.messages on.
  • Resolution: true
• Errors may be given as a hash.
  • Resolution: undecided
• Errors may be given by the end-user as a special ‘error’ object.
  • Resolution undecided
• ActiveModel::Error is necessarily a collection of error objects, each with it’s own 'source' and 'detail'
  • Resolution: that’s how we’ll use it.
• Errors may be automatically generated from the controller.
  • Resolution: deferred
  • 422 for errors…
  • but see https://github.com/rails-api/active_model_serializers/pull/1004#discussion_r46471845 for concerns and alternative implementations

Full Error API Implementation:

• error root key to collection of error objects
  • The members data and errors MUST NOT coexist in the same document.
• error objects from ActiveModel::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.
• detail: a human-readable explanation specific to this occurrence of the problem.
• source: an object containing references to the source of the error, optionally including any of the following members:
  • pointer: 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].
  • parameter: a string indicating which query parameter caused the error.
• meta: a meta object containing non-standard meta-information about the error.

Implementation tests:

• multiple error objects
• serializable resource?
• Controller
  • test/action_controller/json_api/errors_test.rb
  • test/action_controller/rescue_from_test.rb
  • rescue_with_handler, handle_exceptions

Other implementations

ref:

• ams issue: https://github.com/rails-api/active_model_serializers/issues/933
• http://jsonapi.org/format/#error-object
• http://jsonapi.org/examples/
• https://github.com/json-api/json-api/pull/828
• other implementations
  • https://github.com/cerebris/jsonapi-resources/blob/42a3c6409964a0f91544813e9a0437d248832ef4/lib/jsonapi/exceptions.rb
  • https://github.com/cerebris/jsonapi-resources/blob/28ac3971f8b9e73073575d41439ffe263d7e56f5/test/controllers/controller_test.rb#L452-L462
  • https://github.com/cerebris/jsonapi-resources/blob/28ac3971f8b9e73073575d41439ffe263d7e56f5/test/controllers/controller_test.rb#L2412-L2429
  • https://github.com/chingor13/json_api_client/blob/cf79aba96cbc9ff66a793d07f43b025fd8f70b38/lib/json_api_client/error_collector.rb#L34-L48
  • https://github.com/manyminds/api2go/blob/3023e50d563e6ec642b46a4f044812cb232661a1/error.go
  • https://github.com/emberjs/data/blob/1f866da3b4a4edcf70fdf346cd6e6be6cfaecfab/packages/ember-data/lib/adapters/errors.js#L3-L154
  • Usage in Ember
    • http://emberjs.com/blog/2015/06/18/ember-data-1-13-released.html#toc_using-json-api-error-object-format
    • ember-data
      • lib/adapters/errors.js
      • lib/adapters/rest-adapter.js
      • lib/serializers/json-serializer.js
      • adapter-errors-test.js
      • json-serializer-test.js
• libs to review for ideas
  • http://jsonapi.org/implementations/#server-libraries-ruby
  • https://github.com/endpoints/endpoints/blob/master/src/format-jsonapi/index.js
  • https://github.com/chingor13/json_api_client
  • https://github.com/jsmestad/jsonapi-consumer
  • https://github.com/ember-data/active-model-adapter
• libs to consider
  • Hana, JSON Pointer implementations