README.md in request_handler-1.2.0 vs README.md in request_handler-1.3.0
- old
+ new
@@ -1,9 +1,9 @@
# RequestHandler
[](https://badge.fury.io/rb/request_handler)
-[](https://travis-ci.org/runtastic/request_handler)
+[](https://circleci.com/gh/runtastic/request_handler)
[](https://codecov.io/gh/runtastic/request_handler)
This gem allows easy and dry handling of requests based on the dry-validation
gem for validation and data coersion. It allows to handle headers, filters,
include_options, sorting and of course to validate the body.
@@ -34,10 +34,19 @@
separator '____'
validation_engine RequestHandler::Validation::DryEngine
end
```
+JSON:API-style error data can be included in validation errors raised by `RequestHandler`.
+
+```ruby
+RequestHandler.configure do
+ raise_jsonapi_errors = true # default: false
+end
+```
+
+
### Validation Engine
Per default this gem uses the `DryEngine` which relies on dry-validation. All
examples in this Readme assume you are using this default engine. However
you can also use the builtin `DefinitionEngine`, which uses [Definition](https://github.com/Goltergaul/definition) as validation library:
@@ -253,9 +262,47 @@
}
}
```
Please note that each part's content has to be uploaded as a separate file currently.
+
+### JSON:API errors
+
+Errors caused by bad requests respond to `:errors`.
+
+When the gem is configured to `raise_jsonapi_errors`, this method returns a list of hashes
+containing `code`, `status`, `detail`, (`links`) and `source` for each specific issue
+that contributed to the error. Otherwise it returns an empty array.
+
+The exception message contains `<error code>: <source> <detail>` for every issue,
+with one issue per line.
+
+| `:code` | `:status` | What is it? |
+|:--------------------------|:----------|:------------|
+| INVALID_RESOURCE_SCHEMA | 422 | Resource did not pass configured validation |
+| INVALID_QUERY_PARAMETER | 400 | Query parameter violates syntax or did not pass configured validation |
+| MISSING_QUERY_PARAMETER | 400 | Query parameter required in configuration is missing |
+| INVALID_JSON_API | 400 | Request body violates JSON:API syntax |
+| INVALID_MULTIPART_REQUEST | 400 | Sidecar resource missing or invalid JSON |
+
+#### Example
+```ruby
+rescue RequestHandler::SchemaValidationError => e
+ puts e.errors
+end
+```
+
+```ruby
+[
+ {
+ status: '422',
+ code: 'INVALID_RESOURCE_SCHEMA',
+ title: 'Invalid resource',
+ detail: 'is missing',
+ source: { pointer: '/data/attributes/name' }
+ }
+]
+```
### Caveats
It is currently expected that _url_ parameter are already parsed and included in
the request params. With Sinatra requests the following is needed to accomplish