sinja 1.0.0.pre2 → 1.1.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7c550d3cff0b520955dbd6add3f45fe426d0ba03
-  data.tar.gz: 2c0273185088e63db97d8a1de1e6c8612f9999c8
+  metadata.gz: 4491b24eba74ba902735fc26ff679b074bc5a76c
+  data.tar.gz: 54f55fd1b953b7dd31b5bb911386bb6f1bf83419
 SHA512:
-  metadata.gz: beaec25e26829f91f373e886449a64d10629f4905c1fb809576522aa866cd7843bd61c263fb219e566fe17fe2f31c59d0565c5c4230d10e9acd23bd4b09dc781
-  data.tar.gz: d7d470ba61bc03da60129b9e8566b5bd98fdcf7e6223f4e59e72c112bca2fdbfc8d026e209aeb4a651493281a6e38e0f247733ddd906dbefd4c2bce66ee44177
+  metadata.gz: 362031551256e0e28912b13447825269388a54ff698624027ae44e557fc37489686c11427fe43c84b5983d23f8317772c58f5d0185c8373df1e4f43698abf90a
+  data.tar.gz: f282eef01caa1c271f7555f1121f3d2d7fba5e65962a20c10e8e688e380ec67930be8b95002eaad734de1ed9b573421cadaa95b77af6bcea9ef64dd3975e8bf7

data/README.md

@@ -1,17 +1,17 @@
 # Sinja (Sinatra::JSONAPI)
 
-[![Build Status](https://travis-ci.org/mwpastore/sinja.svg?branch=master)](https://travis-ci.org/mwpastore/sinja)
 [![Gem Version](https://badge.fury.io/rb/sinja.svg)](https://badge.fury.io/rb/sinja)
+[![Build Status](https://travis-ci.org/mwpastore/sinja.svg?branch=master)](https://travis-ci.org/mwpastore/sinja)
 
 Sinja is a [Sinatra][1] [extension][10] for quickly building [RESTful][11],
-[JSON:API][2]-[compliant][7] web services, leveraging the excellent
+[{json:api}][2]-[compliant][7] web services, leveraging the excellent
 [JSONAPI::Serializers][3] gem and [Sinatra::Namespace][21] extension. It
 enhances Sinatra's DSL to enable resource-, relationship-, and role-centric
 definition of applications, and it configures Sinatra with the proper settings,
-MIME-types, filters, conditions, and error-handling to implement JSON:API.
+MIME-types, filters, conditions, and error-handling to implement {json:api}.
 Sinja aims to be lightweight (to the extent that Sinatra is), ORM-agnostic (to
 the extent that JSONAPI::Serializers is), and opinionated (to the extent that
-the JSON:API specification is).
+the {json:api} specification is).
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -19,16 +19,18 @@ the JSON:API specification is).
 
 - [Synopsis](#synopsis)
 - [Installation](#installation)
-- [Features](#features)
-  - [Extensibility](#extensibility)
-    - [Public APIs](#public-apis)
+- [Features & Design](#features--design)
+  - [Ol' Blue Eyes is Back](#ol-blue-eyes-is-back)
+  - [Public APIs](#public-apis)
+    - [Commonly Used](#commonly-used)
+    - [Less-Commonly Used](#less-commonly-used)
   - [Performance](#performance)
-  - [Comparison with JSONAPI::Resources (JR)](#comparison-with-jsonapiresources-jr)
-- [Usage](#usage)
+  - [Comparison with JSONAPI::Resources](#comparison-with-jsonapiresources)
+- [Basic Usage](#basic-usage)
   - [Configuration](#configuration)
     - [Sinatra](#sinatra)
     - [Sinja](#sinja)
-  - [Resource Locator](#resource-locator)
+  - [Resource Locators](#resource-locators)
   - [Action Helpers](#action-helpers)
     - [`resource`](#resource)
       - [`index {..}` => Array](#index---array)
@@ -46,11 +48,18 @@ the JSON:API specification is).
       - [`clear {..}` => TrueClass?](#clear---trueclass)
       - [`merge {|rios| ..}` => TrueClass?](#merge-rios---trueclass)
       - [`subtract {|rios| ..}` => TrueClass?](#subtract-rios---trueclass)
-  - [Action Helper Hooks &amp; Utilities](#action-helper-hooks-amp-utilities)
+- [Advanced Usage](#advanced-usage)
+  - [Action Helper Hooks & Utilities](#action-helper-hooks--utilities)
   - [Authorization](#authorization)
     - [`default_roles` configurables](#default_roles-configurables)
     - [`:roles` Action Helper option](#roles-action-helper-option)
     - [`role` helper](#role-helper)
+  - [Query Parameters](#query-parameters)
+  - [Working with Collections](#working-with-collections)
+    - [Filtering](#filtering)
+    - [Sorting](#sorting)
+    - [Paging](#paging)
+    - [Finalizing](#finalizing)
   - [Conflicts](#conflicts)
   - [Validations](#validations)
   - [Missing Records](#missing-records)
@@ -63,8 +72,10 @@ the JSON:API specification is).
       - [Many-to-Many](#many-to-many)
   - [Coalesced Find Requests](#coalesced-find-requests)
   - [Patchless Clients](#patchless-clients)
+- [Application Concerns](#application-concerns)
   - [Sinja or Sinatra::JSONAPI](#sinja-or-sinatrajsonapi)
   - [Code Organization](#code-organization)
+  - [Testing](#testing)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -96,14 +107,14 @@ freeze_jsonapi
 
 Assuming the presence of a `Post` model and serializer, running the above
 "classic"-style Sinatra application would enable the following endpoints (with
-all other JSON:API endpoints returning 404 or 405):
+all other {json:api} endpoints returning 404 or 405):
 
 * `GET /posts/<id>`
 * `GET /posts`
 * `POST /posts`
 
 The resource locator and other action helpers, documented below, enable other
-endpoints.
+endpoints. Please see the [demo-app](/demo-app) for more complete examples.
 
 Of course, "modular"-style Sinatra aplications require you to register the
 extension:
@@ -143,37 +154,40 @@ Or install it yourself as:
 $ gem install sinja
 ```
 
-## Features
+## Features & Design
 
 * ORM-agnostic
-* Role-based authorization
+* Simple role-based authorization
 * To-one and to-many relationships and related resources
 * Side-loaded relationships on resource creation and update
 * Error-handling
   * Conflicts (constraint violations)
   * Missing records
   * Validation failures
-* Plus all the features of JSONAPI::Serializers!
+* Filtering, sorting, and paging collections
+* Plus all the features of [JSONAPI::Serializers][3]!
 
 Its main competitors in the Ruby space are [ActiveModelSerializers][12] (AMS)
-with the JsonApi adapter and [JSONAPI::Resources][8] (JR), both of which are
-designed to work with [Rails][16] and [ActiveRecord][17]/[ActiveModel][18]
-(although they may work with [Sequel][13] via [sequel-rails][14] and Sequel's
-[`:active_model` plugin][15]). Otherwise, you might use something like Sinatra,
-[Roda][20], or [Grape][19] with JSONAPI::Serializers, your own routes, and a
-ton of boilerplate. The goal of this extension is to provide most or all of the
-boilerplate for a Sintara application and automate the drawing of routes based
-on the resource definitions.
-
-### Extensibility
-
-The "power" of implementing this functionality as a Sinatra extension is that
-all of Sinatra's usual features are available within your resource definitions.
-The action helpers blocks get compiled into Sinatra helpers, and the
-`resource`, `has_one`, and `has_many` keywords build [Sinatra::Namespace][21]
-blocks. You can manage caching directives, set headers, and even `halt` (or
-`not_found`, although such cases are usually handled transparently by returning
-`nil` values or empty collections from action helpers) as desired.
+with the JsonApi adapter, [JSONAPI::Resources][8] (JR), and
+[jsonapi-utils][26], all of which are designed to work with [Rails][16] and
+[ActiveRecord][17]/[ActiveModel][18] (although they may work with [Sequel][13]
+via [sequel-rails][14] and Sequel's [`:active_model` plugin][15]). Otherwise,
+you might use something like Sinatra, [Roda][20], or [Grape][19] with
+JSONAPI::Serializers (or another (de)serialization library), your own routes,
+and a ton of boilerplate. The goal of this extension is to provide most or all
+of the boilerplate for a Sintara application and automate the drawing of routes
+based on the resource definitions.
+
+### Ol' Blue Eyes is Back
+
+The "power" so to speak of implementing this functionality as a Sinatra
+extension is that all of Sinatra's usual features are available within your
+resource definitions. The action helpers blocks get compiled into Sinatra
+helpers, and the `resource`, `has_one`, and `has_many` keywords build
+[Sinatra::Namespace][21] blocks. You can manage caching directives, set
+headers, and even `halt` (or `not_found`, although such cases are usually
+handled transparently by returning `nil` values or empty collections from
+action helpers) as appropriate.
 
 ```ruby
 class App < Sinatra::Base
@@ -232,7 +246,7 @@ class App < Sinatra::Base
 
     show do |id|
       book = find(id)
-      not_found "Book #{id} not found!" unless book
+      next unless book
       headers 'X-ISBN'=>book.isbn
       last_modified book.updated_at
       next book, include: %w[author]
@@ -266,13 +280,30 @@ class App < Sinatra::Base
 end
 ```
 
-#### Public APIs
+### Public APIs
+
+Sinja makes a few APIs public to help you work around edge cases in your
+application.
+
+#### Commonly Used
 
 **can?**
 : Takes the symbol of an action helper and returns true if the current user has
   access to call that action helper for the current resource using the `role`
   helper and role definitions detailed under "Authorization" below.
 
+**role?**
+: Takes a list of role(s) and returns true if it has members in common with the
+  current user's role(s).
+
+**sideloaded?**
+: Returns true if the request was invoked from another action helper.
+
+#### Less-Commonly Used
+
+These are helpful if you want to add some custom routes to your Sinja
+application.
+
 **data**
 : Returns the `data` key of the deserialized request payload (with symbolized
   names).
@@ -284,10 +315,6 @@ end
 **dedasherize_names**
 : Takes a hash and returns the hash with its keys dedasherized (deeply).
 
-**role?**
-: Takes a list of role(s) and returns true if it has members in common with the
-  current user's role(s).
-
 **serialize_model**
 : Takes a model (and optional hash of JSONAPI::Serializers options) and returns
   a serialized model.
@@ -306,9 +333,6 @@ end
   and returns a serialized collection if non-empty, or the root metadata if
   present, or a HTTP status 204.
 
-**sideloaded?**
-: Returns true if the request was invoked from another action helper.
-
 ### Performance
 
 Although there is some heavy metaprogramming happening at boot time, the end
@@ -318,60 +342,52 @@ written them verbosely. The main caveat is that there are quite a few block
 closures, which don't perform as well as normal methods in Ruby. Feedback
 welcome.
 
-### Comparison with JSONAPI::Resources (JR)
-
-| Feature         | JR                           | Sinja                                             |
-| :-------------- | :--------------------------- | :------------------------------------------------ |
-| Serializer      | Built-in                     | [JSONAPI::Serializers][3]                         |
-| Framework       | Rails                        | Sinatra, but easy to mount within others          |
-| Routing         | ActionDispatch::Routing      | Mustermann                                        |
-| Caching         | ActiveSupport::Cache         | BYO                                               |
-| ORM             | ActiveRecord/ActiveModel     | BYO                                               |
-| Authorization   | [Pundit][9]                  | Role-based (`roles` keyword and `role` helper)    |
-| Immutability    | `immutable` method           | Omit mutator action helpers                       |
-| Fetchability    | `fetchable_fields` method    | Omit attributes in Serializer                     |
-| Creatability    | `creatable_fields` method    | Handle in `create` action helper or Model\*       |
-| Updatability    | `updatable_fields` method    | Handle in `update` action helper or Model\*       |
-| Sortability     | `sortable_fields` method     | Handle `params[:sort]` in `index` action helper   |
-| Default sorting | `default_sort` method        | Set default for `params[:sort]`                   |
-| Context         | `context` method             | Rack middleware (e.g. `env['context']`)           |
-| Attributes      | Define in Model and Resource | Define in Model\* and Serializer                  |
-| Formatting      | `format` attribute keyword   | Define attribute as a method in Serialier         |
-| Relationships   | Define in Model and Resource | Define in Model, Resource, and Serializer         |
-| Filters         | `filter(s)` keywords         | Handle `params[:filter]` in `index` action helper |
-| Default filters | `default` filter keyword     | Set default for `params[:filter]`                 |
+### Comparison with JSONAPI::Resources
+
+| Feature         | JR                               | Sinja                                             |
+| :-------------- | :------------------------------- | :------------------------------------------------ |
+| Serializer      | Built-in                         | [JSONAPI::Serializers][3]                         |
+| Framework       | Rails                            | Sinatra, but easy to mount within others          |
+| Routing         | ActionDispatch::Routing          | Mustermann                                        |
+| Caching         | ActiveSupport::Cache             | BYO                                               |
+| ORM             | ActiveRecord/ActiveModel         | BYO                                               |
+| Authorization   | [Pundit][9]                      | Role-based                                        |
+| Immutability    | `immutable` method               | Omit mutator action helpers (e.g. `update`)       |
+| Fetchability    | `fetchable_fields` method        | Omit attributes in Serializer                     |
+| Creatability    | `creatable_fields` method        | Handle in `create` action helper or Model\*       |
+| Updatability    | `updatable_fields` method        | Handle in `update` action helper or Model\*       |
+| Sortability     | `sortable_fields` method         | `sort` helper and `:sort_by` option               |
+| Default sorting | `default_sort` method            | Set default for `params[:sort]`                   |
+| Context         | `context` method                 | Rack middleware (e.g. `env['context']`)           |
+| Attributes      | Define in Model and Resource     | Define in Model\* and Serializer                  |
+| Formatting      | `:format` attribute keyword      | Define attribute as a method in Serialier         |
+| Relationships   | Define in Model and Resource     | Define in Model, Resource, and Serializer         |
+| Filters         | `filter(s)` keywords             | `filter` helper and `:filter_by` option           |
+| Default filters | `:default` filter keyword        | Set default for `params[:filter]`                 |
+| Pagination      | JSONAPI::Paginator               | `page` helper and `page_using` configurable       |
+| Meta            | `meta` method                    | Serializer `:meta` option               |
+| Primary keys    | `resource_key_type` configurable | Serializer `id` method               |
 
 \* - Depending on your ORM.
 
-This list is incomplete. TODO:
-
-* Primary keys
-* Pagination
-* Custom links
-* Meta
-* Side-loading (on request and response)
-* Namespaces
-* Configuration
-* Validation
-
-## Usage
+## Basic Usage
 
 You'll need a database schema and models (using the engine and ORM of your
 choice) and [serializers][3] to get started. Create a new Sinatra application
-(classic or modular) to hold all your JSON:API endpoints and (if modular)
+(classic or modular) to hold all your {json:api} endpoints and (if modular)
 register this extension. Instead of defining routes with `get`, `post`, etc. as
 you normally would, define `resource` blocks with action helpers and `has_one`
 and `has_many` relationship blocks (with their own action helpers). Sinja will
 draw and enable the appropriate routes based on the defined resources,
 relationships, and action helpers. Other routes will return the appropriate
-HTTP status codes: 403, 404, or 405.
+HTTP statuses: 403, 404, or 405.
 
 ### Configuration
 
 #### Sinatra
 
 Registering this extension has a number of application-wide implications,
-detailed below. If you have any non-JSON:API routes, you may want to keep them
+detailed below. If you have any non-{json:api} routes, you may want to keep them
 in a separate application and incorporate them as middleware or mount them
 elsewhere (e.g. with [Rack::URLMap][4]), or host them as a completely separate
 web service. It may not be feasible to have custom routes that don't conform to
@@ -381,14 +397,14 @@ these settings.
 * Disables [Rack::Protection][6] (can be reenabled with `enable :protection` or
   by manually `use`-ing the Rack::Protection middleware)
 * Disables static file routes (can be reenabled with `enable :static`)
-* Disables "classy" error pages (in favor of "classy" JSON:API error documents)
-* Adds an `:api_json` MIME-type (`Sinja::MIME_TYPE`)
+* Disables "classy" error pages (in favor of "classy" {json:api} error documents)
+* Adds an `:api_json` MIME-type (`application/vnd.api+json`)
 * Enforces strict checking of the `Accept` and `Content-Type` request headers
 * Sets the `Content-Type` response header to `:api_json` (can be overriden with
   the `content_type` helper)
-* Normalizes query parameters to reflect the features supported by JSON:API
-  (this may be strictly enforced in future versions of Sinja)
-* Formats all errors to the proper JSON:API structure
+* Normalizes and strictly enforces query parameters to reflect the features
+  supported by {json:api}
+* Formats all errors to the proper {json:api} structure
 * Serializes all response bodies (including errors) to JSON
 * Modifies `halt` and `not_found` to raise exceptions instead of just setting
   the status code and body of the response
@@ -414,6 +430,13 @@ configure_jsonapi do |c|
   #c.default_has_one_roles = {}
   #c.default_has_many_roles = {}
 
+  # You can't set this directly; see "Query Parameters" below
+  #c.query_params = {
+  #  :include=>[], :fields=>{}, :filter=>{}, :page=>{}, :sort=>[]
+  #}
+
+  #c.page_using = {} # see "Paging" below
+
   # Set the error logger used by Sinja
   #c.error_logger = ->(error_hash) { logger.error('sinja') { error_hash } }
 
@@ -428,10 +451,10 @@ end
 
 The above structures are mutable (e.g. you can do `c.conflict_exceptions <<
 FooError` and `c.serializer_opts[:meta] = { foo: 'bar' }`) until you call
-`freeze_jsonapi` to freeze the configuration store. You should always freeze
-the store after Sinja is configured and all your resources are defined.
+`freeze_jsonapi` to freeze the configuration store. **You should always freeze
+the store after Sinja is configured and all your resources are defined.**
 
-### Resource Locator
+### Resource Locators
 
 Much of Sinja's advanced functionality (e.g. updating and destroying resources,
 relationship routes) is dependent upon its ability to locate the corresponding
@@ -490,13 +513,10 @@ below. Implicitly return the expected values as described below (as an array if
 necessary) or use the `next` keyword (instead of `return` or `break`) to exit
 the action helper. Return values marked with a question mark below may be
 omitted entirely. Any helper may additionally return an options hash to pass
-along to JSONAPI::Serializer.serialize (will be merged into the global
-`serializer_opts` described above).
-
-The `:include` (see "Side-Unloading Related Resources" below) and `:fields`
-query parameters are automatically passed through to JSONAPI::Serializers. The
-`:sort`, `:page`, and `:filter` query parameters must be handled manually (with
-one exception, discussed under "Coalesced Find Requests" below).
+along to JSONAPI::Serializer.serialize (which will be merged into the global
+`serializer_opts` described above). The `:include` (see "Side-Unloading Related
+Resources" below) and `:fields` (for sparse fieldsets) query parameters are
+automatically passed through to JSONAPI::Serializers.
 
 All arguments to action helpers are "tainted" and should be treated as
 potentially dangerous: IDs, attribute hashes, and (arrays of) [resource
@@ -521,6 +541,11 @@ Return an array of zero or more objects to serialize on the response.
 Take an ID and return the corresponding object (or `nil` if not found) to
 serialize on the response.
 
+##### `show_many {|ids| ..}` => Array
+
+Take an array of IDs and return an equally-lengthed array of objects to
+serialize on the response. See "Coalesced Find Requests" below.
+
 ##### `create {|attr, id| ..}` => id, Object?
 
 With client-generated IDs: Take a hash of (dedasherized) attributes and a
@@ -615,7 +640,9 @@ unless already missing) the relationships on `resource`. To serialize the
 updated linkage on the response, refresh or reload `resource` (if necessary)
 and return a truthy value.
 
-### Action Helper Hooks &amp; Utilities
+## Advanced Usage
+
+### Action Helper Hooks & Utilities
 
 You may remove a previously-registered action helper with `remove_<action>`:
 
@@ -809,11 +836,159 @@ resource :foos do
 end
 ```
 
+Please see the [demo-app](/demo-app) for more complete examples.
+
+### Query Parameters
+
+The {json:api} specification states that any unhandled query parameters should
+cause the request to abort with HTTP status 400. To enforce this requirement,
+Sinja maintains a global "whitelist" of acceptable query parameters as well as
+a per-route whitelist, and interrogates your application to see which features
+it supports; for example, a route may allow a `filter` query parameter, but you
+may not have defined a `filter` helper.
+
+To allow a custom query parameter through, add it to the `query_params`
+configurable with a `nil` value:
+
+```ruby
+configure_jsonapi do |c|
+  c.query_params[:foo] = nil
+end
+```
+
+To let a custom route accept standard query parameters, add a `:qparams` route
+condition:
+
+```ruby
+get '/top10', qparams: [:include, :sort] do
+  # ..
+end
+```
+
+### Working with Collections
+
+#### Filtering
+
+Allow clients to filter the collections returned by the `index` and `fetch`
+action helpers by defining a `filter` helper in the appropriate scope that
+takes a collection and a hash of `filter` query parameters (with its top-level
+keys dedasherized and symbolized) and returns the filtered collection. You may
+also set a `:filter_by` option on the action helper to an array of symbols
+representing the "filter-able" fields for that resource.
+
+For example, to implement simple equality filters using Sequel:
+
+```ruby
+helpers do
+  def filter(collection, fields={})
+    collection.where(fields)
+  end
+end
+
+resource :posts do
+  index(filter_by: [:title, :type]) do
+    Foo # return a Sequel::Dataset (instead of an array of Sequel::Model instances)
+  end
+
+  has_many :comments do
+    fetch(filter_by: :status) do
+      resource.comments_dataset # return a Sequel::Dataset
+    end
+  end
+end
+```
+
+#### Sorting
+
+Allow clients to sort the collections returned by the `index` and `fetch`
+action helpers by defining a `sort` helper in the appropriate scope that takes
+a collection and a hash of `sort` query parameters (with its top-level keys
+dedasherized and symbolized) and returns the sorted collection. The hash values
+are either `:asc` (to sort ascending) or `:desc` (to sort descending). You may
+also set a `:sort_by` option on the action helper to an array of symbols
+representing the "sort-able" fields for that resource.
+
+For example, to implement sorting using Sequel:
+
+```ruby
+helpers do
+  def sort(collection, fields={})
+    collection.order(*fields.map { |k, v| Sequel.send(v, k) })
+  end
+end
+
+resource :posts do
+  index(sort_by: :created_at) do
+    Foo # return a Sequel::Dataset (instead of an array of Sequel::Model instances)
+  end
+end
+```
+
+#### Paging
+
+Allow clients to page the collections returned by the `index` and `fetch`
+action helpers by defining a `page` helper in the appropriate scope that takes
+a collection and a hash of `page` query parameters (with its top-level keys
+dedasherized and symbolized) and returns the paged collection along with a
+special nested hash used to build the paging links.
+
+The top-level keys of the hash returned by this method must be members of the
+set: {`:self`, `:first`, `:prev`, `:next`, `:last`}. The values of the hash are
+hashes themselves containing the query parameters used to construct the
+corresponding link. For example, the hash:
+
+```ruby
+{
+  prev: {
+    number: 3,
+    size: 10
+  },
+  next: {
+    number: 5,
+    size: 10
+  }
+}
+```
+
+Could be used to build the following top-level links in the response document:
+
+```json
+"links": {
+  "prev": "/posts?page[number]=3&page[size]=10",
+  "next": "/posts?page[number]=5&page[size]=10"
+}
+```
+
+You must also set the `page_using` configurable to a hash of symbols
+representing the paging fields used in your application (for example, `:number`
+and `:size` for the above example) along with their default values (or `nil`).
+Please see the [Sequel helpers](/lib/sinja/helpers/sequel.rb) in this
+repository for a detailed, working example.
+
+#### Finalizing
+
+If you need to perform any additional actions on a collection after it is
+filtered, sorted, and/or paged, but before it is serialized, define a
+`finalize` helper that takes a collection and returns the finalized collection.
+For example, to convert Sequel datasets to arrays of models before
+serialization:
+
+```ruby
+helpers do
+  def finalize(collection)
+    collection.all
+  end
+end
+```
+
+(Note that in addition to finalizing Sequel datasets with `#all`, you should
+also enable the `:tactical_eager_loading` plugin for the best compatibility
+with JSONAPI::Serializers.)
+
 ### Conflicts
 
 If your database driver raises exceptions on constraint violations, you should
-specify which exception class(es) should be handled and return HTTP status code
-409.
+specify which exception class(es) should be handled and return HTTP status 409.
 
 For example, using [Sequel][13]:
 
@@ -826,7 +1001,7 @@ end
 ### Validations
 
 If your ORM raises exceptions on validation errors, you should specify which
-exception class(es) should be handled and return HTTP status code 422, along
+exception class(es) should be handled and return HTTP status 422, along
 with a formatter proc that transforms the exception object into an array of
 two-element arrays containing the name or symbol of the attribute that failed
 validation and the detailed errror message for that attribute.
@@ -843,9 +1018,9 @@ end
 ### Missing Records
 
 If your database driver raises exceptions on missing records, you should
-specify which exception class(es) should be handled and return HTTP status code
-404. This is particularly useful for relationship action helpers, which don't
-have access to a dedicated subresource locator.
+specify which exception class(es) should be handled and return HTTP status 404.
+This is particularly useful for relationship action helpers, which don't have
+access to a dedicated subresource locator.
 
 For example, using [Sequel][13]:
 
@@ -904,7 +1079,7 @@ descendents will _not_ be automatically excluded.
 Sinja works hard to DRY up your business logic. As mentioned above, when a
 request comes in to create or update a resource and that request includes
 relationships, Sinja will try to farm out the work to your defined relationship
-routes. Let's look at this example request from the JSON:API specification:
+routes. Let's look at this example request from the {json:api} specification:
 
 ```
 POST /photos HTTP/1.1
@@ -946,7 +1121,7 @@ either `graft` or `create`.
 
 `create` and `update` are the only two action helpers that trigger sideloading;
 `graft`, `merge`, and `clear` are the only action helpers invoked by
-sideloading.  You must indicate which combinations are valid using the
+sideloading. You must indicate which combinations are valid using the
 `:sideload_on` action helper option. (Note that if you want to sideload `merge`
 on `update`, you must define a `clear` action helper as well.) For example:
 
@@ -1074,16 +1249,21 @@ constraints on the join table.
 
 ### Coalesced Find Requests
 
-If your JSON:API client coalesces find requests, the `show` action helper will
+If your {json:api} client coalesces find requests, the `show` action helper will
 be invoked once for each ID in the `:id` filter, and the resulting collection
 will be serialized on the response. Both query parameter syntaxes for arrays
 are supported: `?filter[id]=1,2` and `?filter[id][]=1&filter[id][]=2`. If any
 ID is not found (i.e. `show` returns `nil`), the route will halt with HTTP
-status code 404.
+status 404.
+
+Optionally, to reduce round trips to the database, you may define a "special"
+`show_many` action helper that takes an array of IDs to show. It does not take
+`:roles` or any other options and will only be invoked if the current user has
+access to `show`. This feature is still experimental.
 
 ### Patchless Clients
 
-JSON:API [recommends][23] supporting patchless clients by using the
+{json:api} [recommends][23] supporting patchless clients by using the
 `X-HTTP-Method-Override` request header to coerce a `POST` into a `PATCH`. To
 support this in Sinja, add the Sinja::MethodOverride middleware (which is a
 stripped-down version of [Rack::MethodOverride][24]) into your application (or
@@ -1102,6 +1282,8 @@ class MyApp < Sinatra::Base
 end
 ```
 
+## Application Concerns
+
 ### Sinja or Sinatra::JSONAPI
 
 Everything is dual-namespaced under both Sinatra::JSONAPI and Sinja, and Sinja
@@ -1179,6 +1361,26 @@ class App < Sinatra::Base
 end
 ```
 
+### Testing
+
+The short answer to "How do I test my Sinja application?" is "Like you would
+any other Sinatra application." Unfortunately, the testing story isn't quite
+*there* yet for Sinja. I think leveraging something like [Munson][27] or
+[json_api_client][28] is probably the best bet for integration testing, but
+unfortunately both projects are rife with broken and/or missing critical
+features. And until we can solve the general code organization problem (most
+likely with patches to Sinatra), it will remain difficult to isolate action
+helpers and other artifacts for unit testing.
+
+Sinja's own test suite is based on [Rack::Test][29] (plus some ugly kludges).
+I wouldn't recommend it but it might be a good place to start looking for
+ideas. It leverages the [demo-app](/demo-app) with Sequel and an in-memory
+database to perform integration testing of Sinja's various features under
+MRI/YARV and JRuby. The goal is to free you from worrying about whether your
+applications will behave according to the {json:api} spec (as long as you
+follow the usage documented in this README) and focus on testing your business
+logic.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
@@ -1226,3 +1428,7 @@ License](http://opensource.org/licenses/MIT).
 [23]: http://jsonapi.org/recommendations/#patchless-clients
 [24]: http://www.rubydoc.info/github/rack/rack/Rack/MethodOverride
 [25]: http://www.sinatrarb.com/mustermann/
+[26]: https://github.com/tiagopog/jsonapi-utils
+[27]: https://github.com/coryodaniel/munson
+[28]: https://github.com/chingor13/json_api_client
+[29]: https://github.com/brynary/rack-test