From 1dbd73f95bc31cfd7f437099d919a4c77fcc299e Mon Sep 17 00:00:00 2001 From: Malte-Thorben Bruns Date: Wed, 22 Apr 2015 22:26:15 +0200 Subject: [PATCH] doc: add validate plugin --- README.markdown | 10 +++---- doc/api.markdown | 2 +- doc/plugin-api.markdown | 2 +- doc/plugins.markdown | 63 ++++++++++++++++++++++++++++++----------- 4 files changed, 54 insertions(+), 23 deletions(-) diff --git a/README.markdown b/README.markdown index 97adf69..4ad11a0 100644 --- a/README.markdown +++ b/README.markdown @@ -12,7 +12,7 @@ RAIL is a _mostly_ io.js/node.js core compatible HTTP/RESTful API client and sup The concept of _a single request_ is extended to _a possible series of requests_ further referenced as a _call_. This allows a seamless integration of redirect and authentication mechanisms that require multiple requests to satisfy the original one. -A set of built-in plugins, currently featuring [`buffer`](./doc/plugins.markdown#buffer), [`cookies`](./doc/plugins.markdown#cookies), [`redirect`](./doc/plugins.markdown#redirect) & [`json`](./doc/plugins.markdown#json) make simple requests even simpler, +A set of built-in plugins, currently featuring [`buffer`](./doc/plugins.markdown#buffer), [`cookies`](./doc/plugins.markdown#cookies), [`redirect`](./doc/plugins.markdown#redirect), [`json`](./doc/plugins.markdown#json) & [`validate`](./doc/plugins.markdown#validate) make simple requests even simpler, and a powerful event-driven plugin interface aids in the implementation of complex RESTful API calls. RAIL works with [io.js](https://iojs.org/) 1.x and [node.js](https://nodejs.org/) 0.10.x/0.12.x. @@ -144,10 +144,10 @@ firefox coverage/lcov-report/index.html ### Coverage ``` -Statements : 85.99% ( 399/464 ) -Branches : 79.64% ( 223/280 ) -Functions : 83.93% ( 47/56 ) -Lines : 85.99% ( 399/464 ) +Statements : 88.21% ( 464/526 ) +Branches : 80.46% ( 243/302 ) +Functions : 87.88% ( 58/66 ) +Lines : 88.21% ( 464/526 ) ``` [back to top](#table-of-contents) diff --git a/doc/api.markdown b/doc/api.markdown index d13f8ae..b0872ca 100644 --- a/doc/api.markdown +++ b/doc/api.markdown @@ -4,7 +4,7 @@ An object holding all built-in [plugins](./doc/plugins.markdown). ### RAIL.globalClient -A global `RAIL` object pre-loaded with `buffer`, `json`, `redirect` & `cookies` plugin. +A global `RAIL` object pre-loaded with `buffer`, `json`, `redirect`, `cookies` & `validate` plugin. ### RAIL.call(urlOrOptions, responseListener) A convenience method ala. `https.request()` using `RAIL.globalClient`. diff --git a/doc/plugin-api.markdown b/doc/plugin-api.markdown index 2802c21..a8a1d41 100644 --- a/doc/plugin-api.markdown +++ b/doc/plugin-api.markdown @@ -48,7 +48,7 @@ These events are emitted on the `RAIL` object. ### Event: 'plugin-call' Emitted when a new `Call` object is created. -`function({Call} call, {?Object=} opt_options)` +`function({Call} call, {Object} options)` ### Event: 'plugin-configure' Emitted after a new configuration has been pushed onto the stack. diff --git a/doc/plugins.markdown b/doc/plugins.markdown index e9970a1..6a22cdc 100644 --- a/doc/plugins.markdown +++ b/doc/plugins.markdown @@ -6,6 +6,7 @@ - [cookies](#cookies) - [json](#json) - [redirect](#redirect) + - [validate](#validate) ## buffer Buffers the response body and exports it as `response.buffer`. @@ -13,12 +14,12 @@ When the body is empty its value is `null`, otherwise a `Buffer`. **options** - - `{boolean} default` enable buffering for all requests, defaults to `false` - - `{number} max` max buffer size, defaults to `134217728` (128 MiB) + - `{boolean} default` Enable buffering for all requests, defaults to `false` + - `{number} max` The maximum buffer size, defaults to `134217728` (128 MiB) **request options** - - `{boolean} buffer` en-/disable buffering + - `{boolean} buffer` En-/disable buffering ### buffer.intercept(call) Manually intercept (buffer the response body). To be used by other plugins. @@ -30,7 +31,7 @@ Get/Set cookies. Received cookies are exported as `response.cookies`. **options** - - `{Object} jar` the cookie jar to use, defaults to `{}` + - `{Object} jar` The cookie jar to use, defaults to `{}` **request options** @@ -46,35 +47,65 @@ Uses the `buffer` plugin. **options** - - `{boolean} auto` enable auto-parsing when `Content-Type: application/json` - - `{number} max` max buffer size, defaults to `1048576` (1 MiB) + - `{boolean} auto` Enable auto-parsing when `Content-Type: application/json` + - `{number} max` The maximum buffer size, defaults to `1048576` (1 MiB) **request options** - - `{boolean} json` enable json parsing + - `{boolean} json` Enable JSON parsing + +### json.intercept(call) +Manually intercept (buffer the response body & try to parse). To be used by other plugins. [back to top](#table-of-contents) ## redirect +A configurable redirect mechanism. **options** - - `{Array} codes` codes to react on, defaults to `[301, 302, 308]` - - `{number} limit` max number of redirects, defaults to `1` - - `{boolean} sameHost` only allow redirects to the current host, defaults to `false` - - `{boolean} allowUpgrade` allow switch from `http` to `https/2`, defaults to `true` - - `{boolean} allowDowngrade` allow switch from `https/2` to `http`, defaults to `false` + - `{Array} codes` HTTP status codes to react on, defaults to `[301, 302, 308]` + - `{number} limit` The maximum number of redirects, defaults to `1` + - `{boolean} sameHost` Only allow redirects to the current host, defaults to `false` + - `{boolean} allowUpgrade` Allow switch from `http` to `https/2`, defaults to `true` + - `{boolean} allowDowngrade` Allow switch from `https/2` to `http`, defaults to `false` **request options** - `{Object} redirect` - - `{number} limit` see `options` - - `{boolean} sameHost` see `options` - - `{boolean} allowUpgrade` see `options` - - `{boolean} allowDowngrade` see `options` + - `{number} limit` See `options` + - `{boolean} sameHost` See `options` + - `{boolean} allowUpgrade` See `options` + - `{boolean} allowDowngrade` See `options` ### Event: 'redirect' `function({Object} options)` [back to top](#table-of-contents) + +## validate +A response validation plugin. + +Schema definitions & validation are provided by [mgl-validate](https://www.npmjs.com/package/mgl-validate). + + - Body validation only supports JSON responses + - Every schema requires a unique `id` + - Consider setting `allowUnknownProperties = true` when validating headers + +Uses the `buffer` & `json` plugin. + +**options** + + - `{Array.} schemas` An array of schema definitions + - `{boolean} breakOnError` Whether to return on first validation error or not, defaults to `true` + +**request options** + + - `{Object|string} headers` An existing schema id or a schema definition + - `{Object|string} body` An existing schema id or a schema definition + +### validate.registry +The [mgl-validate](https://www.npmjs.com/package/mgl-validate) schema registry. + +[back to top](#table-of-contents)