lhs 15.5.1 → 15.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 901e6857c26a457c44d35d426b042bc1b697e728867980ae3fbfa5a603538026
-  data.tar.gz: c79f1df56929ec8f612f3efbf4fe8a3f767e3193cefc02f02cfa860602e3cf1e
+  metadata.gz: d0d357a05ee1bf7c6943779c92169c9a411a4b658e20a6adaf651f29d4e743e8
+  data.tar.gz: ad887ed271702978c90da76ec842ec36e616d1f2b549f82b72dfad337cb03805
 SHA512:
-  metadata.gz: 809ae4fe85beeafc1fc720722a92197a5ffd0b248d19bd486a4acfd17283036e7ef321f65893ad3acc9cc2052c438ece6ea7d2e56b53b08b88b39943819c21a3
-  data.tar.gz: '08d18c6e3cd495b780c905abdb7d1c729cf013ced5e6510e1416f597954b9c0037710053a7cc562053c4a0ff89dae7d264dee2d505dba579ff82ca3176cf860f'
+  metadata.gz: 86c1ecd1b8f80b395ca5295a04686c8d596ec36299c8a4e5b22ee917ed8fad83d07dbb778df0146f4a8e42dc3f2f29fa927389ce2376b1e354961560cd9149b2
+  data.tar.gz: 1704037a4744234e2c693eaa2a346f9be12d0f4bfac92790cb12c78671048c15013944632e4bfb410586231a2e37a9141a122753429ad3246eef460831b3b2ab

data/.gitignore

@@ -36,3 +36,4 @@ Gemfile.*.lock
 bower.json
 
 spec/dummy/log/test.log
+spec/dummy/tmp

data/.rubocop.yml

@@ -44,3 +44,6 @@ Naming/PredicateName:
 
 RSpec/MessageSpies:
   Enabled: false
+
+Style/RegexpLiteral:
+  Enabled: false

data/README.md

@@ -1,7 +1,7 @@
 LHS
 ===
 
-LHS uses [LHC](//github.com/local-ch/LHC) for http requests.
+LHS uses [LHC](//github.com/local-ch/LHC) for advanced http requests.
 
 ## Quickstart
 
@@ -9,334 +9,587 @@ LHS uses [LHC](//github.com/local-ch/LHC) for http requests.
 gem 'lhs'
 ```
 
-LHS comes with Request Cycle Cache – enabled by default. It requires [LHC Caching Interceptor](https://github.com/local-ch/lhc/blob/master/docs/interceptors/caching.md) to be enabled:
-
 ```ruby
-# intializers/lhc.rb
+# config/initializers/lhc.rb
+
 LHC.configure do |config|
-  config.interceptors = [LHC::Caching]
+  config.placeholder(:service, 'https://my.service.dev')
 end
 ```
 
-## Very Short Introduction
-
-Access data that is provided by an http JSON service with ease using a LHS::Record.
-
 ```ruby
+# app/models/record.rb
+
 class Record < LHS::Record
 
-  endpoint '{+service}/v2/records'
-  endpoint '{+service}/v2/association/{association_id}/records'
+  endpoint '{+service}/records'
+  endpoint '{+service}/records/{id}'
 
 end
-
-record = Record.find_by(email: 'somebody@mail.com') #<Record>
-record.review # "Lunch was great"
 ```
 
-## Where to store LHS::Records
+```ruby
+# app/controllers/application_controller.rb
+
+record = Record.find_by(email: 'somebody@mail.com')
+record.review # "Lunch was great
+```
+
+## Table of contents
+   * [LHS](#lhs)
+      * [Quickstart](#quickstart)
+      * [Table of contents](#table-of-contents)
+      * [Installation/Startup checklist](#installationstartup-checklist)
+      * [Record](#record)
+         * [Endpoints](#endpoints)
+            * [Configure endpoint hosts](#configure-endpoint-hosts)
+            * [Ambiguous endpoints](#ambiguous-endpoints)
+         * [Record inheritance](#record-inheritance)
+         * [Find multiple records](#find-multiple-records)
+            * [where](#where)
+            * [Reuse/Dry where statements: Use scopes](#reusedry-where-statements-use-scopes)
+            * [Retrieve the amount of a collection of items: count vs. length](#retrieve-the-amount-of-a-collection-of-items-count-vs-length)
+         * [Find single records](#find-single-records)
+            * [find](#find)
+            * [find_by](#find_by)
+            * [first](#first)
+            * [last](#last)
+         * [Work with retrieved data](#work-with-retrieved-data)
+            * [Automatic detection/conversion of collections](#automatic-detectionconversion-of-collections)
+            * [Map complex data for easy access](#map-complex-data-for-easy-access)
+            * [Access and identify nested records](#access-and-identify-nested-records)
+               * [Relations / Associations](#relations--associations)
+                  * [has_many](#has_many)
+                  * [has_one](#has_one)
+            * [Unwrap nested items from the response body](#unwrap-nested-items-from-the-response-body)
+            * [Determine collections from the response body](#determine-collections-from-the-response-body)
+         * [Chain complex queries](#chain-complex-queries)
+            * [Chain where queries](#chain-where-queries)
+            * [Expand plain collections of links: expanded](#expand-plain-collections-of-links-expanded)
+            * [Error handling with chains](#error-handling-with-chains)
+            * [Resolve chains: fetch](#resolve-chains-fetch)
+            * [Add request options to a query chain: options](#add-request-options-to-a-query-chain-options)
+            * [Control pagination within a query chain](#control-pagination-within-a-query-chain)
+         * [Record pagination](#record-pagination)
+            * [Pagination strategy](#pagination-strategy)
+               * [Pagination strategy: offset (default)](#pagination-strategy-offset-default)
+               * [Pagination strategy: page](#pagination-strategy-page)
+               * [Pagination strategy: start](#pagination-strategy-start)
+            * [Pagination keys](#pagination-keys)
+               * [limit_key](#limit_key)
+               * [pagination_key](#pagination_key)
+               * [total_key](#total_key)
+            * [Pagination links](#pagination-links)
+               * [next?](#next)
+               * [previous?](#previous)
+            * [Kaminari support (limited)](#kaminari-support-limited)
+         * [Build, create and update records](#build-create-and-update-records)
+            * [Create new records](#create-new-records)
+               * [create](#create)
+                  * [Unwrap nested data when creation response nests created record data](#unwrap-nested-data-when-creation-response-nests-created-record-data)
+                  * [Create records through associations: Nested sub resources](#create-records-through-associations-nested-sub-resources)
+            * [Start building new records](#start-building-new-records)
+            * [Change/Update existing records](#changeupdate-existing-records)
+               * [save](#save)
+               * [update](#update)
+               * [partial_update](#partial_update)
+            * [Endpoint url parameter injection during record creation/change](#endpoint-url-parameter-injection-during-record-creationchange)
+            * [Record validation](#record-validation)
+               * [Configure record validations](#configure-record-validations)
+               * [HTTP Status Codes for validation errors](#http-status-codes-for-validation-errors)
+               * [Reset validation errors](#reset-validation-errors)
+               * [Add validation errors](#add-validation-errors)
+               * [Validation errors for nested data](#validation-errors-for-nested-data)
+               * [Translation of validation errors](#translation-of-validation-errors)
+               * [Validation error types: errors vs. warnings](#validation-error-types-errors-vs-warnings)
+                  * [Persistance failed: errors](#persistance-failed-errors)
+                  * [Persistance succeeded: warnings](#persistance-succeeded-warnings)
+               * [Using ActiveModel::Validations none the less](#using-activemodelvalidations-none-the-less)
+            * [Use form_helper to create and update records](#use-form_helper-to-create-and-update-records)
+         * [Destroy records](#destroy-records)
+         * [Record getters and setters](#record-getters-and-setters)
+            * [Record setters](#record-setters)
+            * [Record getters](#record-getters)
+         * [Include linked resources (hyperlinks and hypermedia)](#include-linked-resources-hyperlinks-and-hypermedia)
+            * [Ensure the whole linked collection is included: includes_all](#ensure-the-whole-linked-collection-is-included-includes_all)
+            * [Include the first linked page or single item is included: include](#include-the-first-linked-page-or-single-item-is-included-include)
+            * [Include various levels of linked data](#include-various-levels-of-linked-data)
+            * [Identify and cast known records when including records](#identify-and-cast-known-records-when-including-records)
+            * [Apply options for requests performed to fetch included records](#apply-options-for-requests-performed-to-fetch-included-records)
+         * [Record batch processing](#record-batch-processing)
+            * [all](#all)
+               * [Using all, when endpoint does not implement response pagination meta data](#using-all-when-endpoint-does-not-implement-response-pagination-meta-data)
+            * [find_each](#find_each)
+            * [find_in_batches](#find_in_batches)
+         * [Convert/Cast specific record types: becomes](#convertcast-specific-record-types-becomes)
+      * [Request Cycle Cache](#request-cycle-cache)
+         * [Change store for LHS' request cycle cache](#change-store-for-lhs-request-cycle-cache)
+         * [Disable request cycle cache](#disable-request-cycle-cache)
+      * [Testing with LHS](#testing-with-lhs)
+         * [Test helper for request cycle cache](#test-helper-for-request-cycle-cache)
+         * [Test query chains](#test-query-chains)
+            * [By explicitly resolving the chain: fetch](#by-explicitly-resolving-the-chain-fetch)
+            * [Without resolving the chain: where_values_hash](#without-resolving-the-chain-where_values_hash)
+      * [License](#license)
+
+## Installation/Startup checklist
+
+- [ ] Install LHS gem, preferably via `Gemfile`
+- [ ] Configure [LHC](https://github.com/local-ch/lhc) via an `config/initializers/lhc.rb` (See: https://github.com/local-ch/lhc#configuration)
+- [ ] Add `LHC::Caching` to `LHC.config.interceptors` to facilitate LHS' [Request Cycle Cache](#request-cycle-cache)
+- [ ] Store all LHS::Records in `app/models` for autoload/preload reasons
+- [ ] Request data from services via `LHS` from within your rails controllers
+
+## Record
+
+### Endpoints
+
+> Endpoint, the entry point to a service, a process, or a queue or topic destination in service-oriented architecture
+
+Start a record with configuring one or multiple endpoints.
+
+```ruby
+# app/models/record.rb
+
+class Record < LHS::Record
 
-Please store all defined LHS::Records in `app/models` as they are not auto loaded by rails otherwise.
+  endpoint '{+service}/records'
+  endpoint '{+service}/records/{id}'
+  endpoint '{+service}/accociation/{accociation_id}/records'
+  endpoint '{+service}/accociation/{accociation_id}/records/{id}'
 
-## Endpoints
+end
+```
 
-You setup a LHS::Record by configuring one or multiple endpoints. You can also add request options for an endpoint (see following example).
+You can also add request options to be used with configured endpoints:
 
 ```ruby
+# app/models/record.rb
+
 class Record < LHS::Record
 
-  endpoint '{+service}/v2/association/{association_id}/records'
-  endpoint '{+service}/v2/association/{association_id}/records/{id}'
-  endpoint '{+service}/v2/records', auth: { basic: 'PASSWORD' }
-  endpoint '{+service}/v2/records/{id}', auth: { basic: 'PASSWORD' }
+  endpoint '{+service}/records', auth: { bearer: -> { access_token } }
+  endpoint '{+service}/records/{id}', auth: { bearer: -> { access_token } }
 
 end
 ```
 
-### Configuring endpoint hosts
+-> Check [LHC](https://github.com/local-ch/lhc) for more information about request options
 
-Please use placeholders when configuring hosts for endpoints. Otherwise LHS will match them strictly, which can result in problems when a services dynamically returns `hrefs` and mixes `http`, `https` or no protocol at all. See: [LHC Placeholder Configuration](https://github.com/local-ch/lhc/blob/master/docs/configuration.md#placeholders)
+#### Configure endpoint hosts
 
-Please DO NOT mix host placeholders with endpoints (paths), LHS need to know what part of an endpoint is a host and what part of an endpoint is a path, if you use a placeholders in your records endpoint configuration:
+It's common practice to use different hosts accross different environments in a service-oriented architecture.
+
+Use [LHC placeholders](https://github.com/local-ch/lhc#configuring-placeholders) to configure different hosts per environment:
 
-**DO**
 ```ruby
+# config/initializers/lhc.rb
+
 LHC.configure do |config|
-  config.placeholder(:search_service, 'http://tel.search.ch')
+  config.placeholder(:search, ENV['SEARCH'])
 end
+```
+
+```ruby
+# app/models/record.rb
 
 class Record < LHS::Record
 
-  endpoint '{+search_service}/api/search.json'
+  endpoint '{+search}/api/search.json'
 
 end
 ```
 
-**DON'T**
+**DON'T!**
+
+Please DO NOT mix host placeholders with and endpoint's resource path, as otherwise LHS will not work properly.
+
 ```ruby
+# config/initializers/lhc.rb
+
 LHC.configure do |config|
-  config.placeholder(:search_service, 'http://tel.search.ch/api/search.json')
+  config.placeholder(:search, 'http://tel.search.ch/api/search.json')
 end
+```
+
+```ruby
+# app/models/record.rb
 
 class Record < LHS::Record
 
-  endpoint '{+search_service}'
+  endpoint '{+search}'
   
 end
 ```
 
-### Endpoint clashing
+#### Ambiguous endpoints
 
-If you try to setup a LHS::Record with clashing endpoints it will immediately raise an exception.
+If you try to setup a Record with ambiguous endpoints, LHS will immediately raise an exception:
 
 ```ruby
+# app/models/record.rb
+
 class Record < LHS::Record
 
-  endpoint '{+service}/v2/records'
-  endpoint '{+service}/v2/something_else'
+  endpoint '{+service}/records'
+  endpoint '{+service}/bananas'
 
 end
-# raises: Clashing endpoints.
+
+# raises: Ambiguous endpoints
 ```
 
-## Find multiple records
+### Record inheritance
 
-You can query a service for records by using `where`.
+You can inherit from previously defined records and also inherit endpoints that way:
 
 ```ruby
-  Record.where(color: 'blue')
+# app/models/base.rb
+
+class Base < LHS::Record
+  endpoint '{+service}/records/{id}'
+end
 ```
 
-This uses the `{+service}/v2/records` endpoint, cause `{association_id}` was not provided. In addition it would add `?color=blue` to the get parameters.
+```ruby
+# app/models/record.rb
+
+class Record < Base
+end
+```
 
 ```ruby
-  Record.where(association_id: 'fq-a81ngsl1d')
+# app/controllers/some_controller.rb
+
+Record.find(1)
+```
+```
+GET https://service.example.com/records/1
 ```
 
-Uses the `{+service}/v2/association/{association_id}/records` endpoint.
+### Find multiple records
 
-### Expand plain collection of links
+#### fetch
 
-Some endpoints could respond a plain list of links without any expanded data. Like search endpoints.
-If you want to have LHS expand those items, use `expanded` as part of a Query-Chain:
+In case you want to just fetch the records endpoint, without applying any further queries or want to handle pagination, you can simply call `fetch`:
 
-```json
-  {
-    "items" : [
-      {"href": "http://local.ch/customer/1/accounts/1"},
-      {"href": "http://local.ch/customer/1/accounts/2"},
-      {"href": "http://local.ch/customer/1/accounts/3"}
-    ]
-  }
-end
+```ruby
+# app/controllers/some_controller.rb
+
+records = Record.fetch
+
+```
 ```
+  GET https://service.example.com/records
+```
+
+#### where
+
+You can query a service for records by using `where`:
 
 ```ruby
-  Account.where(customer_id: 123).expanded
+# app/controllers/some_controller.rb
+
+Record.where(color: 'blue')
+
+```
+```
+  GET https://service.example.com/records?color=blue
 ```
 
-You can also apply options to `expanded` in order to apply anything on the requests made to expand the links:
+If the provided parameter – `color: 'blue'` in this case – is not part of the endpoint path, it will be added as query parameter.
 
 ```ruby
-  Account.where(customer_id: 123).expanded(auth: { bearer: access_token })
+# app/controllers/some_controller.rb
+
+Record.where(accociation_id: '12345')
+
+```
 ```
+GET https://service.example.com/accociation/12345/records
+```
+
+If the provided parameter – `accociation_id` in this case – is part of the endpoint path, it will be injected into the path:
 
-## Chaining where statements
+#### Reuse/Dry where statements: Use scopes
 
-LHS supports chaining where statements.
-That allows you to chain multiple where-queries:
+In order to reuse/dry where statements organize them in scopes:
 
 ```ruby
+# app/models/record.rb
+
 class Record < LHS::Record
-  endpoint 'records/'
-  endpoint 'records/{id}'
-end
 
-records = Record.where(color: 'blue')
-...
-records.where(available: true).each do |record|
-  ...
+  endpoint '{+service}/records'
+  endpoint '{+service}/records/{id}'
+
+  scope :blue, -> { where(color: 'blue') }
+  scope :available, ->(state) { where(available: state) }
+
 end
 ```
 
-The example would fetch records with the following parameters: `{color: blue, available: true}`.
+```ruby
+# app/controllers/some_controller.rb
+
+records = Record.blue.available(true)
+```
+```
+GET https://service.example.com/records?color=blue&available=true
+```
+
+#### all
+
+You can fetch all remote records by using `all`. Pagination will be performed automatically (See: [Record pagination](#record-pagination))
+
+```ruby
+# app/controllers/some_controller.rb
 
-## Where values hash
+records = Record.all
 
-Returns a hash of where conditions.
-Common to use in tests, as where queries are not performing any HTTP-requests when no data is accessed.
+```
+```
+  GET https://service.example.com/records?limit=100
+  GET https://service.example.com/records?limit=100&offset=100
+  GET https://service.example.com/records?limit=100&offset=200
+```
 
 ```ruby
-records = Record.where(color: 'blue').where(available: true).where(color: 'red')
+# app/controllers/some_controller.rb
 
-expect(
-  records
-).to have_requested(:get, %r{records/})
-  .with(query: hash_including(color: 'blue', available: true))
-# will fail as no http request is made (no data requested)
+records.size # 300
 
-expect(
-  records.where_values_hash
-).to eq {color: 'red', available: true}
 ```
 
-## Scopes: Reuse where statements
+#### all with unpaginated endpoints
 
-In order to make common where statements reusable you can organize them in scopes:
+In case your record endpoints are not implementing any pagination, configure it to be `paginated: false`. Pagination will not be performed automatically in those cases:
 
 ```ruby
+# app/models/record.rb
+
 class Record < LHS::Record
-  endpoint 'records/'
-  endpoint 'records/{id}'
-  scope :blue, -> { where(color: 'blue') }
-  scope :available, ->(state) { where(available: state) }
+  configuration paginated: false
 end
 
-records = Record.blue.available(true)
-The example would fetch records with the following parameters: `{color: blue, visible: true}`.
 ```
 
-## Error handling with chains
+```ruby
+# app/controllers/some_controller.rb
 
-One benefit of chains is lazy evaluation. This means they get resolved when data is accessed. This makes it hard to catch errors with normal `rescue` blocks.
+records = Record.all
 
-To simplify error handling with chains, you can also chain error handlers to be resolved, as part of the chain.
+```
+```
+  GET https://service.example.com/records
+```
 
-In case no matching error handler is found the error gets re-raised.
+#### Retrieve the amount of a collection of items: count vs. length
 
-```ruby
-record = Record.where(color: 'blue')
-  .handle(LHC::BadRequest, ->(error){ show_error })
-  .handle(LHC::Unauthorized, ->(error){ authorize })
-```
+The different behavior of `count` and `length` is based on ActiveRecord's behavior.
 
-[List of possible error classes](https://github.com/local-ch/lhc/tree/master/lib/lhc/errors)
+`count` The total number of items available remotly via the provided endpoint/api, communicated via pagination meta data.
 
-If an error handler returns `nil` an empty LHS::Record is returned, not `nil`!
+`length` The number of items already loaded from the endpoint/api and kept in memmory right now. In case of a paginated endpoint this can differ to what `count` returns, as it depends on how many pages have been loaded already.
 
-In case you want to ignore errors and continue working with `nil` in those cases,
-please use `ignore`:
+### Find single records
+
+#### find
+
+`find` finds a unique record by unique identifier (usually `id` or `href`). If no record is found an error is raised.
 
 ```ruby
-record = Record.ignore(LHC::NotFound).find_by(color: 'blue')
-record # nil
+Record.find(123)
+```
+```
+GET https://service.example.com/records/123
 ```
 
-## Resolve chains
+```ruby
+Record.find('https://anotherservice.example.com/records/123')
+```
+```
+GET https://anotherservice.example.com/records/123
+```
 
-LHS Chains can be resolved with `fetch`, similar to ActiveRecord:
+`find` can also be used to find a single unique record with parameters:
 
 ```ruby
-records = Record.where(color: 'blue').fetch
+Record.find(another_identifier: 456)
+```
+```
+GET https://service.example.com/records?another_identifier=456
 ```
 
-## Find single records
-
-`find` finds a unique record by unique identifier (usually id or href).
+You can also fetch multiple records by `id` in parallel:
 
 ```ruby
-  Record.find(123)
-  Record.find('https://api.example.com/records/123')
+Record.find(1, 2, 3)
+```
+```
+# In parallel:
+  GET https://service.example.com/records/1
+  GET https://service.example.com/records/2
+  GET https://service.example.com/records/3
 ```
 
-If no record is found an error is raised.
+#### find_by
 
-`find` can also be used to find a single unique record with parameters:
+`find_by` finds the first record matching the specified conditions. If no record is found, `nil` is returned.
+
+`find_by!` raises `LHC::NotFound` if nothing was found.
 
 ```ruby
-  Record.find(association_id: 123, id: 456)
+Record.find_by(color: 'blue')
+```
+```
+GET https://service.example.com/records?color=blue
 ```
 
-`find_by` finds the first record matching the specified conditions.
+#### first
 
-If no record is found, `nil` is returned.
+`first` is an alias for finding the first record without parameters. If no record is found, `nil` is returned.
 
-`find_by!` raises LHC::NotFound if nothing was found.
+`first!` raises `LHC::NotFound` if nothing was found.
 
 ```ruby
-  Record.find_by(id: 'z12f-3asm3ngals')
-  Record.find_by(id: 'doesntexist') # nil
+Record.first
+```
+```
+GET https://service.example.com/records?limit=1
 ```
 
-`first` is an alias for finding the first record without parameters.
+`first` can also be used with options:
 
 ```ruby
-  Record.first
+Record.first(params: { color: :blue })
+```
+```
+GET https://service.example.com/records?color=blue&limit=1
 ```
 
-If no record is found, `nil` is returned.
+#### last
 
-`first!` raises LHC::NotFound if nothing was found.
+`last` is an alias for finding the last record without parameters. If no record is found, `nil` is returned.
 
-`first` can also be used with options:
+`last!` raises `LHC::NotFound` if nothing was found.
 
 ```ruby
-Record.first(params: { color: :blue })
+Record.last
 ```
 
-`last` is an alias for finding the last record without parameters.
+`last` can also be used with options:
 
 ```ruby
-  Record.last
+Record.last(params: { color: :blue })
 ```
 
-If no record is found, `nil` is returned.
+### Work with retrieved data
 
-`last!` raises LHC::NotFound if nothing was found.
-
-`last` can also be used with options:
+After fetching [single](#find-single-records) or [multiple](#find-multiple-records) records you can navigate the received data with ease:
 
 ```ruby
-Record.last(params: { color: :blue })
+records = Record.where(color: 'blue')
+records.length # 4
+records.count # 400
+record = records.first
+record.type # 'Business'
+record[:type] # 'Business'
+record['type'] # 'Business'
 ```
 
-# Find multiple single records in parallel
+#### Automatic detection/conversion of collections
+
+How to configure endpoints for automatic collection detection?
+
+LHS detects automatically if the responded data is a single business object or a set of business objects (collection).
+
+Conventionally, when the responds contains an `items` key `{ items: [] }` it's treated as a collection, but also if the responds contains a plain raw array: `[{ href: '' }]` it's also treated as a collection.
+
+If you need to configure the attribute of the response providing the collection, configure `items_key` as explained here: (Determine collections from the response body)[#determine-collections-from-the-response-body]
+
+#### Map complex data for easy access
 
-In case you want to fetch multiple records by id in parallel, you can also do this with `find`:
+To influence how data is accessed, simply create methods inside your Record to access complex data structures:
 
 ```ruby
-Record.find(1, 2, 3)
+# app/models/record.rb
+
+class Record < LHS::Record
+
+  endpoint '{+service}/records'
+
+  def name
+    dig(:addresses, :first, :business, :identities, :first, :name)
+  end
+end
 ```
 
-If you want to inject values for the failing records, that might not have been found, you can inject values for them with error handlers:
+#### Access and identify nested records
+
+Nested records, in nested data, are automatically casted to the correct Record class, when they provide an `href` and that `href` matches any defined endpoint of any defined Record:
 
 ```ruby
-data = Record
-  .handle(LHC::Unauthorized, ->(response) { Record.new(name: 'unknown') })
-  .find(1, 2, 3)
-data[1].name # 'unknown'
+# app/models/place.rb
+
+class Place < LHS::Record
+  endpoint '{+service}/places'
+  endpoint '{+service}/places/{id}'
+
+  def name
+    dig(:addresses, :first, :business, :identities, :first, :name)
+  end
+end
 ```
 
-## Navigate data
+```ruby
+# app/models/favorite.rb
 
-After fetching [single](#find-single-records) or [multiple](#find-multiple-records) records you can navigate the received data with ease.
+class Favorite < LHS::Record
+  endpoint '{+service}/favorites'
+  endpoint '{+service}/favorites/{id}'
+end
+```
 
 ```ruby
-  records = Record.where(color: 'blue')
-  records.collection? # true
-  record = records.first
-  record.item? # true
-  record.parent == records # true
+# app/controllers/some_controller.rb
+
+favorite = Favorite.includes(:place).find(123)
+favorite.place.name # local.ch AG
+```
+```
+GET https://service.example.com/favorites/123
+
+{... place: { href: 'https://service.example.com/places/456' }}
+
+GET https://service.example.com/places/456
 ```
 
-## Relations
+If automatic detection of nested records does not work, make sure your Records are stored in `app/models`! See: (Insallation/Startup checklist)[#installation-startup-checklist]
 
-Even though, nested data is automatically casted when accessed, see: [Nested records](#nested-records), sometimes api's don't provide dedicated endpoints to retrieve these records.
+##### Relations / Associations
 
-As those records also don't have an href, nested records can not be casted automatically, when accessed.
+Typically nested data is automatically casted when accessed (See: [Access and identify nested records](#access-and-identify-nested-records)), but sometimes API's don't provide dedicated endpoints to retrieve these records.
+In those cases, those records are only available through other records and don't have an `href` on their own and can't be casted automatically, when accessed. 
 
-Those kind of relations, you can still configure manually, using `has_many` and `has_one`:
+To be able to implement Record-specific logic for those nested records, you can define relations/associations.
+
+###### has_many
 
-### Relations
 ```ruby
+# app/models/location.rb
 
 class Location < LHS::Record
 
-  endpoint 'http://uberall/locations/{id}'
+  endpoint '{+service}/locations/{id}'
 
   has_many :listings
 
 end
+```
+
+```ruby
+# app/models/listing.rb
 
 class Listing < LHS::Record
 
@@ -344,20 +597,57 @@ class Listing < LHS::Record
     type == 'SUPPORTED'
   end
 end
+```
+
+```ruby
+# app/controllers/some_controller.rb
 
 Location.find(1).listings.first.supported? # true
+```
+```
+GET https://service.example.com/locations/1
+{... listings: [{ type: 'SUPPORTED' }] }
+```
+
+`class_name`: Specify the class name of the relation. Use it only if that name can't be inferred from the relation name. So has_many :photos will by default be linked to the Photo class, but if the real class name is e.g. CustomPhoto or namespaced Custom::Photo, you'll have to specify it with this option.
+
+```ruby
+# app/models/custom/location.rb
+
+module Custom
+  class Location < LHS::Record
+    endpoint '{+service}/locations'
+    endpoint '{+service}/locations/{id}'
+    
+    has_many :photos, class_name: 'Custom::Photo'
+  end
+end
+```
+
+```ruby
+# app/models/custom/photo.rb
 
+module Custom
+  class Photo < LHS::Record
+  end
+end
 ```
 
+###### has_one
+
 ```ruby
+# app/models/transaction.rb
 
 class Transaction < LHS::Record
 
-  endpoint 'http://myservice/transaction/{id}'
+  endpoint '{+service}/transaction/{id}'
 
   has_one :user
-
 end
+```
+
+```ruby
+# app/models/user.rb
 
 class User < LHS::Record
 
@@ -365,1019 +655,1564 @@ class User < LHS::Record
     self[:email_address]
   end
 end
-
-Transaction.find(1).user.email_address # steve@local.ch
-
 ```
 
-### Options
-
-In case you have to configure relations, the following relation options are available:
+```ruby
+# app/controllers/some_controller.rb
 
-`class_name`: Specify the class name of the relation. Use it only if that name can't be inferred from the relation name. So has_many :photos will by default be linked to the Photo class, but if the real class name is e.g. UberallPhoto or namespaced Uberall::Photo, you'll have to specify it with this option.
+Transaction.find(1).user.email_address # steve@local.ch
+```
+```
+GET https://service.example.com/transaction/1
+{... user: { email_address: 'steve@local.ch' } }
+```
 
-e.g.
+`class_name`: Specify the class name of the relation. Use it only if that name can't be inferred from the relation name. So has_many :photos will by default be linked to the Photo class, but if the real class name is e.g. CustomPhoto or namespaced Custom::Photo, you'll have to specify it with this option.
 
 ```ruby
-module Uberall
+# app/models/custom/location.rb
+
+module Custom
   class Location < LHS::Record
-    endpoint 'http://uberall/locations'
-    endpoint 'http://uberall/locations/:id'
+    endpoint '{+service}/locations'
+    endpoint '{+service}/locations/{id}'
     
-    has_many :photos, class_name: 'Uberall::Photo'
+    has_one :photo, class_name: 'Custom::Photo'
   end
 end
+```
 
-module Uberall
+```ruby
+# app/models/custom/photo.rb
+
+module Custom
   class Photo < LHS::Record
   end
 end
 ```
 
-## Request based options
+#### Unwrap nested items from the response body
+
+If the actual item data is mixed with meta data in the response body, LHS allows you to configure a record in a way to automatically unwrap items from within nested response data.
+
+`item_key` is used to unwrap the actual object from within the response body.
 
-You can apply options to the request chain. Those options will be forwarded to the request perfomed by the chain/query.
+```ruby
+# app/models/location.rb
+
+class Location < LHS::Record
+  configuration item_key: [:response, :location]
+end
+```
 
 ```ruby
-  # Authenticate with OAuth
-  options = { auth: { bearer: '123456' } }
+# app/controllers/some_controller.rb
 
-  AuthenticatedRecord = Record.options(options)
+location = Location.find(123)
+location.id # 123
+```
+```
+GET https://service.example.com/locations/123
+{... response: { location: { id: 123 } } }
+```
 
-  blue_records = AuthenticatedRecord.where(color: 'blue')
-  active_records = AuthenticatedRecord.where(active: true)
+#### Determine collections from the response body
 
-  AuthenticatedRecord.create(color: 'red')
+`items_key` key used to determine the collection of items of the current page (e.g. `docs`, `items`, etc.), defaults to 'items':
 
-  record = AuthenticatedRecord.find(123)
-  # Find resolves the current query and applies all options from the chain
-  # All further requests are made from scratch and not based on the previous options
-  record.name = 'Walter'
+```ruby
+# app/models/search.rb
 
-  authenticated_record = record.options(options)
-  authenticated_record.valid?
-  authenticated_record.save
-  authenticated_record.destroy
-  authenticated_record.update(name: 'Steve')
+class Search < LHS::Record
+  configuration items_key: :docs
+end
 ```
 
-## Request Cycle Cache
-
-By default, LHS does not perform the same http request during one request cycle multiple times.
+```ruby
+# app/controllers/some_controller.rb
 
-It uses the [LHC Caching Interceptor](https://github.com/local-ch/lhc/blob/master/docs/interceptors/caching.md) as caching mechanism base and sets a unique request id for every request cycle with Railties to ensure data is just cached within one request cycle and not shared with other requests.
+search_result = Search.where(q: 'Starbucks')
+search_result.first.address # Bahnhofstrasse 5, 8000 Zürich
+```
+```
+GET https://service.example.com/search?q=Starbucks
+{... docs: [... {...  address: 'Bahnhofstrasse 5, 8000 Zürich' }] }
+```
 
-Only GET requests are considered for caching by using LHC Caching Interceptor's `cache_methods` option internally and considers request headers when caching requests, so requests with different headers are not served from cache.
+### Chain complex queries
 
-The LHS Request Cycle Cache is opt-out, so it's enabled by default and will require you to enable the [LHC Caching Interceptor](https://github.com/local-ch/lhc/blob/master/docs/interceptors/caching.md) in your project.
+> [Method chaining](https://en.wikipedia.org/wiki/Method_chaining), also known as named parameter idiom, is a common syntax for invoking multiple method calls in object-oriented programming languages. Each method returns an object, allowing the calls to be chained together without requiring variables to store the intermediate results
 
-If you want to disable the LHS Request Cycle Cache, simply disable it within configuration:
+In order to simplify and enhance preparing complex queries for performing single or multiple requests, LHS implements query chains to find single or multiple records. 
 
-```ruby
-LHS.config.request_cycle_cache_enabled = false
-```
+LHS query chains do [lazy evaluation](https://de.wikipedia.org/wiki/Lazy_Evaluation) to only perform as many requests as needed, when the data to be retrieved is actually needed.
 
-By default the LHS Request Cycle Cache will use `ActiveSupport::Cache::MemoryStore` as its cache store. Feel free to configure a cache that is better suited for your needs by:
+Any method, accessing the content of the data to be retrieved, is resolving the chain in place – like `.each`, `.first`, `.some_attribute_name`. Nevertheless, if you just want to resolve the chain in place, and nothing else, `fetch` should be the method of your choice:
 
 ```ruby
-LHS.config.request_cycle_cache = ActiveSupport::Cache::MemoryStore.new
-```
+# app/controllers/some_controller.rb
 
-## Batch processing
-
-**Be careful using methods for batch processing. They could result in a lot of HTTP requests!**
+Record.where(color: 'blue').fetch
+```
 
-`all` fetches all records from the service by doing multiple requests and resolving endpoint pagination if necessary.
+#### Chain where queries
 
 ```ruby
-data = Record.all
-data.count # 998
-data.length # 998
+# app/controllers/some_controller.rb
+
+records = Record.where(color: 'blue')
+[...]
+records.where(available: true).each do |record|
+  [...]
+end
+```
+```
+  GET https://service.example.com/records?color=blue&available=true
 ```
 
-`all` is chainable and has the same interface like `where` (See: [Find multiple records](https://github.com/local-ch/lhs#find-multiple-records))
+In case you wan't to check/debug the current values for where in the chain, you can use `where_values_hash`:
 
 ```ruby
-Record.where(color: 'blue').all
-Record.all.where(color: 'blue')
-Record.all(color: 'blue')
-# All three are doing the same thing: fetching all records with the color 'blue' from the endpoint while resolving pagingation if endpoint is paginated
+records.where_values_hash
+
+# {color: 'blue', available: true}
 ```
 
-In case an API does not provide pagination information (limit, offset and total), LHS keeps on loading pages when requesting `all` until the first empty page responds.
+#### Expand plain collections of links: expanded
 
-[Count vs. Length](#count-vs-length)
+Some endpoints could respond only with a plain list of links and without any expanded data, like search results.
 
-`find_each` is a more fine grained way to process single records that are fetched in batches.
+Use `expanded` to have LHS expand that data, by performing necessary requests in parallel:
 
 ```ruby
-Record.find_each(start: 50, batch_size: 20, params: { has_reviews: true }) do |record|
-  # Iterates over each record. Starts with record no. 50 and fetches 20 records each batch.
-  record
-  break if record.some_attribute == some_value
-end
+# app/controllers/some_controller.rb
+
+Search.where(what: 'Cafe').expanded
 ```
+```
+GET https://service.example.com/search?what=Cafe
+{...
+  "items" : [
+    {"href": "https://service.example.com/records/1"},
+    {"href": "https://service.example.com/records/2"},
+    {"href": "https://service.example.com/records/3"}
+  ]
+}
+
+In parallel:
+  > GET https://service.example.com/records/1
+  < {... name: 'Cafe Einstein'}
+  > GET https://service.example.com/records/2
+  < {... name: 'Starbucks'}
+  > GET https://service.example.com/records/3
+  < {... name: 'Plaza Cafe'}
+
+{
+  ...
+  "items" : [
+    {
+      "href": "https://service.example.com/records/1",
+      "name": 'Cafe Einstein',
+      ...
+    },
+    {
+      "href": "https://service.example.com/records/2",
+      "name": 'Starbucks',
+      ...
+    },
+    {
+      "href": "https://service.example.com/records/3",
+      "name": 'Plaza Cafe',
+      ...
+    }
+  ]
+}
+```
+
+You can also apply request options to `expanded`. Those options will be used to perform the additional requests to expand the data:
 
-`find_in_batches` is used by `find_each` and processes batches.
 ```ruby
-Record.find_in_batches(start: 50, batch_size: 20, params: { has_reviews: true }) do |records|
-  # Iterates over multiple records (batch size is 20). Starts with record no. 50 and fetches 20 records each batch.
-  records
-  break if records.first.name == some_value
-end
+# app/controllers/some_controller.rb
+
+Search.where(what: 'Cafe').expanded(auth: { bearer: access_token })
 ```
 
-## Create records
+#### Error handling with chains
+
+One benefit of chains is lazy evaluation. But that also means they only get resolved when data is accessed. This makes it hard to catch errors with normal `rescue` blocks:
 
 ```ruby
-  record = Record.create(
-    recommended: true,
-    source_id: 'aaa',
-    content_ad_id: '1z-5r1fkaj'
-  )
+# app/controllers/some_controller.rb
+
+def show
+  @records = Record.where(color: blue) # returns a chain, nothing is resolved, no http requests are performed
+rescue => e
+  # never ending up here, because the http requests are actually performed in the view, when the query chain is resolved
+end
 ```
 
-See [Validation](#validation) for handling validation errors when creating records.
+```ruby
+# app/views/some/view.haml
+
+= @records.each do |record| # .each resolves the query chain, leads to http requests beeing performed, which might raises an exception
+  = record.name
+```
 
-### Endpoint paramters and paramter injection during creation
+To simplify error handling with chains, you can also chain error handlers to be resolved, as part of the chain.
 
-LHS injects body parameters to generate target urls, used for creation requests:
+If you need to render some different view in Rails based on an LHS error raised during rendering the view, please proceed as following:
 
 ```ruby
-class Favorite << LHS::Record
-  endpoint '{+datastore}/content-ads/{content_ad_id}/feedbacks'
+# app/controllers/some_controller.rb
+
+def show
+  @records = Record
+    .handle(LHC::Error, ->(error){ handle_error(error) })
+    .where(color: 'blue')
+  render 'show'
+  render_error if @error
+end
+
+private
+
+def handle_error(error)
+  @error = error
+  nil
 end
 
-Favorite.create(content_ad_id: 51232, text: 'Great Restaurant!')
-# POST http://datastore/content_ads/51232
-# body: '{ "text" : "Great Restaurant!" }'
+def render_error
+  self.response_body = nil # required to not raise AbstractController::DoubleRenderError
+  render 'error'
+end
+```
 ```
+> GET https://service.example.com/records?color=blue
+< 406
+```
+
+In case no matching error handler is found the error gets re-raised.
 
-Because API's usually reject body paramters for foreign key attributes:
+-> Read more about [LHC error types/classes](https://github.com/local-ch/lhc#exceptions)
 
+If you want to inject values for the failing records, that might not have been found, you can inject values for them with error handlers:
+
+```ruby
+# app/controllers/some_controller.rb
+
+data = Record
+  .handle(LHC::Unauthorized, ->(response) { Record.new(name: 'unknown') })
+  .find(1, 2, 3)
+
+data[1].name # 'unknown'
 ```
-Not allowed to set or change foreign key: content_ad_id!
 ```
+In parallel:
+  > GET https://service.example.com/records/1
+  < 200
+  > GET https://service.example.com/records/2
+  < 400
+  > GET https://service.example.com/records/3
+  < 200
+```
+
+-> Read more about [LHC error types/classes](https://github.com/local-ch/lhc#exceptions)
 
-We remove it from the body, if the information was instead transported through the URL.
+**If an error handler returns `nil` an empty LHS::Record is returned, not `nil`!**
 
-### Create records through associations (nested resources)
+In case you want to ignore errors and continue working with `nil` in those cases,
+please use `ignore`:
 
 ```ruby
-  class Review < LHS::Record
-    endpoint '{+service}/reviews'
-  end
+# app/controllers/some_controller.rb
 
-  class Comment < LHS::Record
-    endpoint '{+service}/reviews/{review_id/}comments'
-  end
+record = Record.ignore(LHC::NotFound).find_by(color: 'blue')
+
+record # nil
+```
+
+#### Resolve chains: fetch
+
+In case you need to resolve a query chain in place, use `fetch`:
+
+```ruby
+# app/controllers/some_controller.rb
+
+records = Record.where(color: 'blue').fetch
 ```
 
-#### Item
+#### Add request options to a query chain: options
+
+You can apply options to the request chain. Those options will be forwarded to the request perfomed by the chain/query:
+
 ```ruby
-  review = Review.find(1)
-  # Review#1
-  # :href => '{+service}/reviews/1
-  # :text => 'Simply awesome'
-  # :comment => { :href => '{+service}/reviews/1/comments }
+# app/controllers/some_controller.rb
 
-  review.comment.create(text: 'Thank you!')
-  # Comment#1
-  # :href => '{+service}/reviews/1/comments
-  # :text => 'Thank you!'
+options = { auth: { bearer: '123456' } } # authenticated with OAuth token
 
-  review
-  # Review#1
-  # :href => '{+service}/reviews/1
-  # :text => 'Simply awesome'
-  # :comment => { :href => '{+service}/reviews/1/comments, :text => 'Thank you!' }
 ```
 
-If the item already exists `ArgumentError` is raised.
+```ruby
+# app/controllers/some_controller.rb
+
+AuthenticatedRecord = Record.options(options)
+
+```
 
-#### Expanded collection
 ```ruby
-  review = Review.includes(:comments).find(1)
-  # Review#1
-  # :href => '{+service}/reviews/1'
-  # :text => 'Simply awesome'
-  # :comments => { :href => '{+service}/reviews/1/comments, :items => [] }
+# app/controllers/some_controller.rb
 
-  review.comments.create(text: 'Thank you!')
-  # Comment#1
-  # :href => '{+service}/reviews/1/comments/1'
-  # :text => 'Thank you!'
+blue_records = AuthenticatedRecord.where(color: 'blue')
 
-  review
-  # Review#1
-  # :href => '{+service}/reviews/1'
-  # :text => 'Simply awesome'
-  # :comments => { :href => '{+service}/reviews/1/comments, :items => [{ :href => '{+service}/reviews/1/comments/1', :text => 'Thank you!' }] }
+```
+```
+GET https://service.example.com/records?color=blue { headers: { 'Authentication': 'Bearer 123456' } }
 ```
 
-#### Not expanded collection
 ```ruby
-  review = Review.find(1)
-  # Review#1
-  # :href => '{+service}/reviews/1'
-  # :text => 'Simply awesome'
-  # :comments => { :href => '{+service}/reviews/1/comments' }
+# app/controllers/some_controller.rb
 
-  review.comments.create(text: 'Thank you!')
-  # Comment#1
-  # :href => '{+service}/reviews/1/comments/1'
-  # :text => 'Thank you!'
+AuthenticatedRecord.create(color: 'red')
 
-  review
-  # Review#1
-  # :href => '{+service}/reviews/1
-  # :text => 'Simply awesome'
-  # :comments => { :href => '{+service}/reviews/1/comments', :items => [{ :href => '{+service}/reviews/1/comments/1', :text => 'Thank you!' }] }
 ```
+```
+POST https://service.example.com/records { body: '{ color: "red" }' }, headers: { 'Authentication': 'Bearer 123456' } }
+```
+
+```ruby
+# app/controllers/some_controller.rb
 
-## Build new records
+record = AuthenticatedRecord.find(123)
 
-Build and persist new items from scratch are done either with `new` or it's alias `build`.
+```
+```
+GET https://service.example.com/records/123 { headers: { 'Authentication': 'Bearer 123456' } }
+```
 
 ```ruby
-  record = Record.new(recommended: true)
-  record.save
+# app/controllers/some_controller.rb
+
+authenticated_record = record.options(options) # starting a new chain based on the found record
+
 ```
 
-### Endpoint parameters and paramter injection for saving records
+```ruby
+# app/controllers/some_controller.rb
+
+authenticated_record.valid?
 
-See: [Endpoint paramters and paramter injection during creation](#endpoint-paramters-and-paramter-injection-during-creation)
+```
+```
+POST https://service.example.com/records/validate { body: '{...}', headers: { 'Authentication': 'Bearer 123456' } }
+```
 
-## Custom setters and getters
+```ruby
+# app/controllers/some_controller.rb
 
-Sometimes it is the case that you want to have your custom getters and setters and convert the data to a processable format behind the scenes.
-The initializer will now use custom setter if one is defined:
+authenticated_record.save
+```
+```
+POST https://service.example.com/records { body: '{...}', headers: { 'Authentication': 'Bearer 123456' } }
+```
 
 ```ruby
+# app/controllers/some_controller.rb
 
-module RatingsConversions
-  def ratings=(values)
-    super(
-      values.map { |k, v| { name: k, value: v } }
-    )
-  end
-end
+authenticated_record.destroy
 
-class Record < LHS::Record
-  prepend RatingsConversions
-end
+```
+```
+DELETE https://service.example.com/records/123 { headers: { 'Authentication': 'Bearer 123456' } }
+```
 
-record = Record.new(ratings: { quality: 3 })
-record.ratings # [{ :name=>:quality, :value=>3 }]
+```ruby
+# app/controllers/some_controller.rb
 
+authenticated_record.update(name: 'Steve')
+
+```
 ```
+POST https://service.example.com/records/123 { body: '{...}', headers: { 'Authentication': 'Bearer 123456' } }
+```
+
+#### Control pagination within a query chain
+
+`page` sets the page that you want to request.
+
+`per` sets the amount of items requested per page.
 
-If you have an accompanying getter the whole data manipulation would be internal only.
+`limit` is an alias for `per`. **But without providing arguments, it resolves the query and provides the current response limit per page**
 
 ```ruby
-module RatingsConversions
-  def ratings=(values)
-    super(
-      values.map { |k, v| { name: k, value: v } }
-    )
-  end
+# app/controllers/some_controller.rb
 
-  def ratings
-    super.map { |r| [r[:name], r[:value]] }]
-  end
-end
+Record.page(3).per(20).where(color: 'blue')
 
-class Record < LHS::Record
-  prepend RatingsConversions
-end
+```
+```
+GET https://service.example.com/records?offset=40&limit=20&color=blue
+```
 
-record = Record.new(ratings: { quality: 3 }) # [{ :name=>:quality, :value=>3 }]
-record.ratings # {:quality=>3}
+```ruby
+# app/controllers/some_controller.rb
+
+Record.page(3).per(20).where(color: 'blue')
 
+```
+```
+GET https://service.example.com/records?offset=40&limit=20&color=blue
 ```
 
-## Include linked resources
+The applied pagination strategy depends on whats configured for the particular record: See [Record pagination](#record-pagination)
 
-When fetching records, you can specify in advance all the linked resources that you want to include in the results. With `includes` or `includes_all` (to enforce fetching all remote objects for paginated endpoints), LHS ensures that all matching and explicitly linked resources are loaded and merged.
+### Record pagination
 
-The implementation is heavily influenced by [http://guides.rubyonrails.org/active_record_class_querying](http://guides.rubyonrails.org/active_record_class_querying.html#eager-loading-associations) and you should read it to understand this feature in all its glory.
+You can configure pagination on a per record base. 
+LHS differentiates between the [pagination strategy](#pagination-strategy) (how items/pages are navigated and calculated) and [pagination keys](#pagination-keys) (how stuff is named and accessed).
 
-### `includes_all` for paginated endpoints
+#### Pagination strategy
 
-In case endpoints are paginated and you are certain that you'll need all objects of a set and not only the first page/batch, use `includes_all`.
+##### Pagination strategy: offset (default)
 
-LHS will ensure that all linked resources are around by loading all pages (parallelized/performance optimized).
+The offset pagination strategy is LHS's default pagination strategy, so nothing needs to be (re-)configured.
+
+The `offset` pagination strategy starts with 0 and offsets by the amount of items, thay you've already recived – typically `limit`.
 
 ```ruby
-customer = Customer.includes_all(contracts: :products).find(1)
+# app/models/record.rb
 
-# GET http://datastore/customers/1
-# GET http://datastore/customers/1/contracts?limit=100
-# GET http://datastore/customers/1/contracts?limit=10&offset=10
-# GET http://datastore/customers/1/contracts?limit=10&offset=20
-# GET http://datastore/products?limit=100
-# GET http://datastore/products?limit=10&offset=10
+class Search < LHS::Record
+  endpoint '{+service}/search'
+end
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+Record.all
 
-customer.contracts.length # 33
-customer.contracts.first.products.length # 22
 ```
+```
+GET https://service.example.com/records?limit=100
+{
+  items: [{...}, ...]
+  total: 300,
+  limit: 100,
+  offset: 0
+}
+In parallel:
+  GET https://service.example.com/records?limit=100&offset=100
+  GET https://service.example.com/records?limit=100&offset=200
+```
+
+##### Pagination strategy: page
 
-### One-Level `includes`
+In comparison to the `offset` strategy, the `page` strategy just increases by 1 (page) and sends the next batch of items for the next page.
 
 ```ruby
-  # a claim has a localch_account
-  claims = Claims.includes(:localch_account).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
-  claims.first.localch_account.email # 'test@email.com'
+# app/models/record.rb
+
+class Search < LHS::Record
+  configuration pagination_strategy: 'page', pagination_key: 'page'
+
+  endpoint '{+service}/search'
+end
 ```
 
-Before include:
-```json
+```ruby
+# app/controllers/some_controller.rb
+
+Record.all
+
+```
+```
+GET https://service.example.com/records?limit=100
 {
-  "href" : "http://datastore/v2/places/huU90mB_6vAfUdVz_uDoyA/claims",
-  "items" : [
-    {
-      "href" : "http://datastore/v2/localch-accounts/6bSss0y93lK0MrVsgdNNdg/claims/huU90mB_6vAfUdVz_uDoyA",
-      "localch_account" : {
-        "href" : "http://datastore/v2/localch-accounts/6bSss0y93lK0MrVsgdNNdg"
-      }
-    }
-  ]
+  items: [{...}, ...]
+  total: 300,
+  limit: 100,
+  page: 1
 }
+In parallel:
+  GET https://service.example.com/records?limit=100&page=2
+  GET https://service.example.com/records?limit=100&page=3
 ```
 
-After include:
-```json
+##### Pagination strategy: start
+
+In comparison to the `offset` strategy, the `start` strategy indicates with which item the current page starts. 
+Typically it starts with 1 and if you get 100 items per page, the next start is 101.
+
+```ruby
+# app/models/record.rb
+
+class Search < LHS::Record
+  configuration pagination_strategy: 'start', pagination_key: 'startAt'
+
+  endpoint '{+service}/search'
+end
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+Record.all
+
+```
+```
+GET https://service.example.com/records?limit=100
 {
-  "href" : "http://datastore/v2/places/huU90mB_6vAfUdVz_uDoyA/claims",
-  "items" : [
-    {
-      "href" : "http://datastore/v2/localch-accounts/6bSss0y93lK0MrVsgdNNdg/claims/huU90mB_6vAfUdVz_uDoyA",
-      "localch_account" : {
-        "href" : "http://datastore/v2/localch-accounts/6bSss0y93lK0MrVsgdNNdg",
-        "id" : "6bSss0y93lK0MrVsgdNNdg",
-        "name" : "Myriam",
-        "phone" : "12345678",
-        "email" : "email@gmail.com"
-      }
-    }
-  ]
+  items: [{...}, ...]
+  total: 300,
+  limit: 100,
+  page: 1
 }
+In parallel:
+  GET https://service.example.com/records?limit=100&startAt=101
+  GET https://service.example.com/records?limit=100&startAt=201
 ```
 
-### Two-Level `includes`
+#### Pagination keys
+
+##### limit_key
+
+`limit_key` sets the key used to indicate how many items you want to retrieve per page e.g. `size`, `limit`, etc.
+In case the `limit_key` parameter differs for how it needs to be requested from how it's provided in the reponse, use `body` and `parameter` subkeys.
 
 ```ruby
-  # a record has a association, which has an entry
-  records = Record.includes(association: :entry).where(has_reviews: true)
-  records.first.association.entry.name # 'Casa Ferlin'
+# app/models/record.rb
+
+class Record < LHS::Record
+  configuration limit_key: { body: [:pagination, :max], parameter: :max }
+
+  endpoint '{+service}/records'
+end
 ```
 
-### Multiple `includes`
+```ruby
+# app/controllers/some_controller.rb
+
+records = Record.where(color: 'blue')
+records.limit # 20
+```
+```
+GET https://service.example.com/records?color=blue&max=100
+{ ...
+  items: [...],
+  pagination: { max: 20 }
+}
+```
+
+##### pagination_key
+
+`pagination_key` defines which key to use to paginate a page (e.g. `offset`, `page`, `startAt` etc.).
+In case the `limit_key` parameter differs for how it needs to be requested from how it's provided in the reponse, use `body` and `parameter` subkeys.
 
 ```ruby
-  # list of includes
-  claims = Claims.includes(:localch_account, :entry).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
+# app/models/record.rb
 
-  # array of includes
-  claims = Claims.includes([:localch_account, :entry]).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
+class Record < LHS::Record
+  configuration pagination_key: { body: [:pagination, :page], parameter: :page }, pagination_strategy: :page
 
-  # Two-level with array of includes
-  records = Record.includes(campaign: [:entry, :user]).where(has_reviews: true)
+  endpoint '{+service}/records'
+end
 ```
 
-### Known LHS::Records are used to request linked resources
+```ruby
+# app/controllers/some_controller.rb
 
-When including linked resources with `includes`, known/defined services and endpoints are used to make those requests.
-That also means that options for endpoints of linked resources are applied when requesting those in addition.
-This allows you to include protected resources (e.g. Basic auth) as endpoint options for oauth authentication get applied.
+records = Record.where(color: 'blue').all
+records.length # 300
+```
+```
+GET https://service.example.com/records?color=blue&limit=100
+{... pagination: { page: 1 } }
+In parallel:
+  GET https://service.example.com/records?color=blue&limit=100&page=2
+  {... pagination: { page: 2 } }
+  GET https://service.example.com/records?color=blue&limit=100&page=3
+  {... pagination: { page: 3 } }
+```
+
+##### total_key
 
-The [Auth Inteceptor](https://github.com/local-ch/lhc-core-interceptors#auth-interceptor) from [lhc-core-interceptors](https://github.com/local-ch/lhc-core-interceptors) is used to configure the following endpoints.
+`total_key` defines which key to user for pagination to describe the total amount of remote items (e.g. `total`, `totalResults`, etc.).
 
 ```ruby
-class Favorite < LHS::Record
+# app/models/record.rb
 
-  endpoint '{+service}/{user_id}/favorites', auth: { basic: { username: 'steve', password: 'can' } }
-  endpoint '{+service}/{user_id}/favorites/:id', auth: { basic: { username: 'steve', password: 'can' } }
+class Record < LHS::Record
+  configuration total_key: [:pagination, :total]
 
+  endpoint '{+service}/records'
 end
+```
 
-class Place < LHS::Record
+```ruby
+# app/controllers/some_controller.rb
 
-  endpoint '{+service}/v2/places', auth: { basic: { username: 'steve', password: 'can' } }
-  endpoint '{+service}/v2/places/{id}', auth: { basic: { username: 'steve', password: 'can' } }
+records = Record.where(color: 'blue').fetch
+records.length # 100
+records.count # 300
+```
+```
+GET https://service.example.com/records?color=blue&limit=100
+{... pagination: { total: 300 } }
+```
 
-end
+#### Pagination links
 
-Favorite.includes(:place).where(user_id: current_user.id)
-# Will include places and applies endpoint options to authenticate the request.
+##### next?
+
+`next?` Tells you if there is a next link or not.
+
+```ruby
+# app/controllers/some_controller.rb
+
+@records = Record.where(color: 'blue').fetch
+```
 ```
+GET https://service.example.com/records?color=blue&limit=100
+{... items: [...], next: 'https://service.example.com/records?color=blue&limit=100&offset=100' }
+```
+
+```ruby
+# app/views/some_view.haml
 
-### Forward options used for request made to include referenced resources
+- if @records.next?
+  = render partial: 'next_arrow'
+```
 
-Provide options to the requests made to include referenced resources:
+##### previous?
 
+`previous?` Tells you if there is a previous link or not.
+
+```ruby
+# app/controllers/some_controller.rb
+
+@records = Record.where(color: 'blue').fetch
+```
+```
+GET https://service.example.com/records?color=blue&limit=100
+{... items: [...], previous: 'https://service.example.com/records?color=blue&limit=100&offset=100' }
 ```
 
-  Favorite.includes(:place).references(place: { auth: { bearer: '123' }})
+```ruby
+# app/views/some_view.haml
 
+- if @records.previous?
+  = render partial: 'previous_arrow'
 ```
 
-## Map data
+#### Kaminari support (limited)
 
-To influence how data is accessed/provided, you can use mappings to either map deep nested data or to manipulate data when its accessed. Simply create methods inside the LHS::Record. They can access underlying data:
+LHS implements an interface that makes it partially working with Kaminari.
+
+The kaminari’s page parameter is in params[:page]. For example, you can use kaminari to render paginations based on LHS Records. Typically, your code will look like this:
 
 ```ruby
-class LocalEntry < LHS::Record
-  endpoint ':service/v2/local-entries'
+# controller
+@items = Record.page(params[:page]).per(100)
+```
 
-  def name
-    addresses.first.business.identities.first.name
-  end
+```ruby
+# view
+= paginate @items
+```
 
-end
+### Build, create and update records
+
+#### Create new records
+
+##### create
+
+`create` will return false if persisting fails. `create!` instead will an raise exception.
+
+`create` always builds the data of the local object first, before it tries to sync with an endpoint. So even if persisting fails, the local object is build.
+
+```ruby
+# app/controllers/some_controller.rb
+
+record = Record.create(
+  text: 'Hello world'
+)
+
+```
 ```
+POST https://service.example.com/records { body: "{ 'text' : 'Hello world' }" }
+```
+
+-> See [record validation](#record-validation) for how to handle validation errors when creating records.
 
-## Nested records
+###### Unwrap nested data when creation response nests created record data
 
-Nested records (in nested data) are automatically casted when the href matches any defined endpoint of any LHS::Record.
+`item_created_key` key used to merge record data thats nested in the creation response body:
 
 ```ruby
-class Place < LHS::Record
-  endpoint '{+service}/v2/places'
+# app/models/location.rb
+
+class Location < LHS::Record
+
+  configuration item_created_key: [:response, :location]
 
-  def name
-    addresses.first.business.identities.first.name
-  end
 end
+```
 
-class Favorite < LHS::Record
-  endpoint '{+service}/v2/favorites'
+```ruby
+# app/controllers/some_controller.rb
+
+location.create(lat: '47.3920152', long: '8.5127981')
+location.address # Förrlibuckstrasse 62, 8005 Zürich
+```
+```
+POST https://service.example.com/locations { body: "{ 'lat': '47.3920152', long: '8.5127981' }" }
+{... { response: { location: {... address: 'Förrlibuckstrasse 62, 8005 Zürich' } } } } 
+```
+
+###### Create records through associations: Nested sub resources
+
+```ruby
+# app/models/restaurant.rb
+
+class Restaurant < LHS::Record
+  endpoint '{+service}/restaurants/{id}'
 end
 
-favorite = Favorite.includes(:place).find(1)
-favorite.place.name # local.ch AG
 ```
 
-If automatic-detection of nested records does not work, make sure your LHS::Records are stored in `app/models`!
+```ruby
+# app/models/feedback.rb
 
-## Setters
+class Feedback < LHS::Record
+  endpoint '{+service}/restaurants/{restaurant_id}/feedbacks'
+end
 
-You can change attributes of LHS::Records:
+```
 
 ```ruby
-  record = Record.find(id: 'z12f-3asm3ngals')
-  rcord.recommended = false
+# app/controllers/some_controller.rb
+
+restaurant = Restaurant.find(1)
+```
+```
+GET https://service.example.com/restaurants/1
+{... reviews: { href: 'https://service.example.com/restaurants/1/reviews' }}
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+restaurant.reviews.create(
+  text: 'Simply awesome!'
+)
+```
+```
+POST https://service.example.com/restaurants/1/reviews { body: "{ 'text': 'Simply awesome!' }" }
 ```
 
-## Save
+#### Start building new records
 
-You can persist changes with `save`. `save` will return `false` if persisting fails. `save!` instead will raise an exception.
+With `new` or `build` you can start building new records from scratch, which can be persisted with `save`:
 
 ```ruby
-  record = Record.find('1z-5r1fkaj')
-  record.recommended = false
-  record.save
+# app/controllers/some_controller.rb
+
+record = Record.new # or Record.build
+record.name = 'Starbucks'
+record.save
+```
+```
+POST https://service.example.com/records { body: "{ 'name' : 'Starbucks' }" }
 ```
 
-## Update
+#### Change/Update existing records
 
-`update` will return false if persisting fails. `update!` instead will an raise exception.
+##### save
 
-`update` always updates the data of the local object first, before it tries to sync with an endpoint. So even if persisting fails, the local object is updated.
+`save` persist the whole object in it's current state. 
+
+`save` will return `false` if persisting fails. `save!` instead will raise an exception.
 
 ```ruby
+# app/controllers/some_controller.rb
+
 record = Record.find('1z-5r1fkaj')
-record.update(recommended: false)
+
+```
+```
+GET https://service.example.com/records/1z-5r1fkaj
+{ name: 'Starbucks', recommended: null }
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+record.recommended = true
+record.save
+
+```
 ```
+POST https://service.example.com/records/1z-5r1fkaj { body: "{ 'name': 'Starbucks', 'recommended': true }" }
+```
+
+-> See [record validation](#record-validation) for how to handle validation errors when updating records.
 
-### Endpoint paramters and paramter injection during updates
+##### update
 
-LHS injects body parameters to generate target urls, used for update requests:
+`update` persists the whole object after new parameters are applied through arguments.
+
+`update` will return false if persisting fails. `update!` instead will an raise exception.
+
+`update` always updates the data of the local object first, before it tries to sync with an endpoint. So even if persisting fails, the local object is updated.
 
 ```ruby
-class Customer << LHS::Record
-  endpoint '{+customers}/{id}'
-end
+# app/controllers/some_controller.rb
 
-customer = Customer.find(123)
-# GET http://customers/123
-# { id: '123', name: 'My old company name' }
+record = Record.find('1z-5r1fkaj')
 
-customer.update(name: 'My new company name')
-# POST http://customers/123
-# body: { "name": 'My new company name' }
+```
+```
+GET https://service.example.com/records/1z-5r1fkaj
+{ name: 'Starbucks', recommended: null }
 ```
 
-Because API's usually reject body paramters for primary identifiers:
+```ruby
+# app/controllers/some_controller.rb
+
+record.update(recommended: true)
 
 ```
-Not allowed to change primary id!
+```
+POST https://service.example.com/records/1z-5r1fkaj { body: "{ 'name': 'Starbucks', 'recommended': true }" }
 ```
 
-We remove it from the body, if the information was instead transported through the URL.
+-> See [record validation](#record-validation) for how to handle validation errors when updating records.
 
-## Partial Update
+##### partial_update
 
-Often you just want to update a single attribute on an existing record. As ActiveRecord's `update_attribute` skips validation, which is unlikely with api services, and `update_attributes` is just an alias for `update`, LHS introduces `partial_update` for that matter.
+`partial_update` updates just the provided parameters.
 
 `partial_update` will return false if persisting fails. `partial_update!` instead will an raise exception.
 
 `partial_update` always updates the data of the local object first, before it tries to sync with an endpoint. So even if persisting fails, the local object is updated.
 
 ```ruby
+# app/controllers/some_controller.rb
+
 record = Record.find('1z-5r1fkaj')
-record.partial_update(recommended: false)
-# POST /records/1z-5r1fkaj
-{
-  recommended: true
+
+```
+```
+GET https://service.example.com/records/1z-5r1fkaj
+{ name: 'Starbucks', recommended: null }
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+record.partial_update(recommended: true)
+
+```
+```
+POST https://service.example.com/records/1z-5r1fkaj { body: "{ 'name': 'Starbucks', 'recommended': true }" }
+```
+
+-> See [record validation](#record-validation) for how to handle validation errors when updating records.
+
+#### Endpoint url parameter injection during record creation/change
+
+LHS injects parameters provided to `create`, `update`, `partial_update`, `save` etc. into an endpoint's URL when matching:
+
+```ruby
+# app/models/feedback.rb
+
+class Feedback << LHS::Record
+  endpoint '{+service}/records/{record_id}/feedbacks'
+end
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+Feedback.create(record_id: 51232, text: 'Great Restaurant!')
+```
+```
+POST https://service.example.com/records/51232/feedbacks { body: "{ 'text' : 'Great Restaurant!' }" }
+```
+
+#### Record validation
+
+In order to validate records before persisting them, you can use the `valid?` (`validate` alias) method.
+
+It's **not recommended** to validate records anywhere, including application side validation via `ActiveModel::Validations`, except, if you validate them via the same endpoint/service, that also creates them.
+
+The specific endpoint has to support validations without persistence. An endpoint has to be enabled (opt-in) in your record configurations:
+
+```ruby
+# app/models/user.rb
+
+class User < LHS::Record
+
+  endpoint '{+service}/users', validates: { params: { persist: false } }
+
+end
+```
+
+```ruby
+# app/controllers/some_controller.rb
+
+user = User.build(email: 'i\'m not an email address')
+
+unless user.valid?
+  @errors = user.errors
+  render 'new' and return
+end
+```
+```
+POST https://service.example.com/users?persist=false { body: '{ "email" : "i'm not an email address"}' }
+{ 
+  "field_errors": [{
+    "path": ["email"],
+    "code": "WRONG_FORMAT",
+    "message": "The property value's format is incorrect."
+  }],
+  "message": "Email must have the correct format."
 }
 ```
 
-## Becomes
+The functionalities of `LHS::Errors` pretty much follow those of `ActiveModel::Validation`:
 
-Based on [ActiveRecord's implementation](http://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-becomes), LHS implements `becomes`, too.
-It's a way to convert records of a certain type A to another certain type B.
+```ruby
+# app/views/some_view.haml
 
-_NOTE: RPC-style actions, that are discouraged in REST anyway, are utilizable with this functionality, too. See the following example:_
+@errors.any? # true
+@errors.include?(:email) # true
+@errors[:email] # ['WRONG_FORMAT']
+@errors.messages # {:email=>["Translated error message that this value has the wrong format"]}
+@errors.codes # {:email=>["WRONG_FORMAT"]}
+@errors.message # Email must have the correct format."
+```
+
+##### Configure record validations
+
+The parameters passed to the `validates` endpoint option are used to perform record validations:
 
 ```ruby
-class Location < LHS::Record
-  endpoint 'http://sync/locations'
-  endpoint 'http://sync/locations/{id}'
+# app/models/user.rb
+
+class User < LHS::Record
+
+  endpoint '{+service}/users', validates: { params: { persist: false } }  # will add ?persist=false to the request
+  endpoint '{+service}/users', validates: { params: { publish: false } }  # will add ?publish=false to the request
+  endpoint '{+service}/users', validates: { params: { validates: true } } # will add ?validates=true to the request
+  endpoint '{+service}/users', validates: { path: 'validate' }            # will perform a validation via ...users/validate
+
 end
+```
 
-class Synchronization < LHS::Record
-  endpoint 'http://sync/locations/{id}/sync'
+##### HTTP Status Codes for validation errors
+
+The HTTP status code received from the endpoint when performing validations on a record, is available through the errors object:
+
+```ruby
+# app/controllers/some_controller.rb
+
+record.save
+record.errors.status_code # 400
+```
+
+##### Reset validation errors
+
+Clear the error messages like:
+
+```ruby
+# app/controllers/some_controller.rb
+
+record.errors.clear
+```
+
+##### Add validation errors
+
+In case you want to add application side validation errors, even though it's not recommended, do it as following:
+
+```ruby
+user.errors.add(:name, 'WRONG_FORMAT')
+```
+
+##### Validation errors for nested data
+
+If you work with complex data structures, you sometimes need to have validation errors delegated/scoped to nested data.
+
+This features makes `LHS::Record`s compatible with how Rails or Simpleform renders/builds forms and especially error messages:
+
+```ruby
+# app/controllers/some_controller.rb
+
+unless @customer.save
+  @errors = @customer.errors
 end
+```
+```
+POST https://service.example.com/customers { body: "{ 'address' : { 'street': 'invalid', housenumber: '' } }" }
+{ 
+  "field_errors": [{
+    "path": ["address", "street"],
+    "code": "REQUIRED_PROPERTY_VALUE_INCORRECT",
+    "message": "The property value is incorrect."
+  },{
+    "path": ["address", "housenumber"],
+    "code": "REQUIRED_PROPERTY_VALUE",
+    "message": "The property value is required."
+  }],
+  "message": "Some data is invalid."
+}
+```
 
-location = Location.find(1)
-synchronization = location.becomes(Synchronization)
-synchronization.save!
+```ruby
+# app/views/some_view.haml
+
+= form_for @customer, as: :customer do |customer_form|
+
+  = fields_for 'customer[:address]', @customer.address, do |address_form|
+
+    = fields_for 'customer[:address][:street]', @customer.address.street, do |street_form|
+
+      = street_form.input :name
+      = street_form.input :house_number
+```
+
+This would render nested forms and would also render nested form errors for nested data structures.
+
+You can also access those nested errors like:
+
+```ruby
+@customer.address.errors
+@customer.address.street.errors
+```
+
+##### Translation of validation errors
+
+If a translation exists for one of the following translation keys, LHS will provide a translated error (also in the following order) rather than the plain error message/code, when building forms or accessing `@errors.messages`:
+
+```ruby
+lhs.errors.records.<record_name>.attributes.<attribute_name>.<error_code>
+e.g. lhs.errors.records.customer.attributes.name.unsupported_property_value
+
+lhs.errors.records.<record_name>.<error_code>
+e.g. lhs.errors.records.customer.unsupported_property_value
+
+lhs.errors.messages.<error_code>
+e.g. lhs.errors.messages.unsupported_property_value
+
+lhs.errors.attributes.<attribute_name>.<error_code>
+e.g. lhs.errors.attributes.name.unsupported_property_value
+
+lhs.errors.fallback_message
+```
+
+##### Validation error types: errors vs. warnings
+
+###### Persistance failed: errors
+
+If an endpoint returns errors in the response body, that is enough to interpret it as: persistance failed.
+The response status code in this scenario is neglected.
+
+###### Persistance succeeded: warnings
+
+In some cases, you need non blocking meta information about potential problems with the created record, so called warnings.
+
+If the API endpoint implements warnings, returned when validating, they are provided just as `errors` (same interface and methods) through the `warnings` attribute:
+
+```ruby
+# app/controllres/some_controller.rb
+
+@presence = Presence.options(params: { synchronize: false }).create(
+  place: { href: 'http://storage/places/1' }
+)
+```
+```
+POST https://service.example.com/presences { body: '{ "place": { "href": "http://storage/places/1" } }' }
+{
+    field_warnings: [{
+      code: 'WILL_BE_RESIZED',
+      path: ['place', 'photos', 0],
+      message: 'This photo is too small and will be resized.'
+    }
+  }
+```
+
+```ruby
+
+presence.warnings.any? # true
+presence.place.photos[0].warnings.messages.first # 'This photo is too small and will be resized.'
+
+```
+
+##### Using `ActiveModel::Validations` none the less
+
+If you are using `ActiveModel::Validations`, even though it's not recommended, and you add errors to the LHS::Record instance, then those errors will be overwritten by the errors from `ActiveModel::Validations` when using `save`  or `valid?`. 
+
+So in essence, mixing `ActiveModel::Validations` and LHS built-in validations (via endpoints), is not compatible, yet.
+
+[Open issue](https://github.com/local-ch/lhs/issues/159)
+
+#### Use form_helper to create and update records
+
+Rails `form_for` view-helper can be used in combination with instances of `LHS::Record`s to autogenerate forms:
+
+```ruby
+<%= form_for(@instance, url: '/create') do |f| %>
+  <%= f.text_field :name %>
+  <%= f.text_area :text %>
+  <%= f.submit "Create" %>
+<% end %>
 ```
 
-## Destroy
+### Destroy records
+
+`destroy`  deletes a record.
+
+```ruby
+# app/controllers/some_controller.rb
 
-You can delete records remotely by calling `destroy` on an LHS::Record.
+record = Record.find('1z-5r1fkaj')
+```
+```
+GET https://service.example.com/records/1z-5r1fkaj
+```
 
 ```ruby
-  record = Record.find('1z-5r1fkaj')
-  record.destroy
+# app/controllers/some_controller.rb
+
+record.destroy
+```
+```
+DELETE https://service.example.com/records/1z-5r1fkaj
 ```
 
 You can also destroy records directly without fetching them first:
 
 ```ruby
-  destroyed_record = Record.destroy('1z-5r1fkaj')
+# app/controllers/some_controller.rb
+
+destroyed_record = Record.destroy('1z-5r1fkaj')
+```
+```
+DELETE https://service.example.com/records/1z-5r1fkaj
 ```
 
 or with parameters:
 
 ```ruby
-  destroyed_records = Record.destroy(name: 'Steve')
+# app/controllers/some_controller.rb
+
+destroyed_records = Record.destroy(name: 'Steve')
+```
+```
+DELETE https://service.example.com/records?name='Steve'
 ```
 
-## Validation
+### Record getters and setters
 
-In order to validate LHS::Records before persisting them, you can use the `valid?` (`validate` alias) method.
+Sometimes it is neccessary to implement custom getters and setters and convert data to a processable (endpoint) format behind the scenes.
 
-It's not recommended to validate records anywhere but with the endpoint that also provides to create them.
+#### Record setters
 
-The specific endpoint has to support validations without persistence. An endpoint has to be enabled (opt-in) for validations in the service configuration.
+You can define setter methods in `LHS::Record`s that will be used by initializers (`new`) and setter methods, that convert data provided, before storing it in the record and persisting it with a remote endpoint:
 
 ```ruby
-class User < LHS::Record
-  endpoint '{+service}/v2/users', validates: { params: { persist: false } }
-end
+# app/models/user.rb
 
-user = User.build(email: 'i\'m not an email address')
-unless user.valid?
-  fail(user.errors[:email])
-end
+class Feedback < LHS::Record
 
-user.errors #<LHS::Problems::Errors>
-user.errors.include?(:email) # true
-user.errors[:email] # ['REQUIRED_PROPERTY_VALUE']
-user.errors.messages # {:email=>["Translated error message that this value is required"]}
-user.errors.codes # {:email=>["REQUIRED_PROPERTY_VALUE"]}
-user.errors.message # email must be set when user is created."
+  def ratings=(values)
+    super(
+      values.map { |k, v| { name: k, value: v } }
+    )
+  end
+end
 ```
 
-The parameters passed to the `validates` endpoint option are used to perform the validation:
-
 ```ruby
-  endpoint '{+service}/v2/users', validates: { params: { persist: false } }  # will add ?persist=false to the request
-  endpoint '{+service}/v2/users', validates: { params: { publish: false } }  # will add ?publish=false to the request
-  endpoint '{+service}/v2/users', validates: { params: { validates: true } } # will add ?validates=true to the request
-  endpoint '{+service}/v2/users', validates: { path: 'validate' }            # will perform a validation via :service/v2/users/validate
-```
-
-### HTTP Status Codes for validation errors
-
-LHS provides the http status code received when performing validations on a record, through the errors object:
+# app/controllers/some_controller.rb
 
-```ruby
-record.save
-record.errors.status_code #400
+record = Record.new(ratings: { quality: 3 })
+record.ratings # [{ :name=>:quality, :value=>3 }]
 ```
 
-### Reset validation errors
+#### Record getters
 
-Clear the error messages. Compatible with [ActiveRecord](https://github.com/rails/rails/blob/6c8cf21584ced73ade45529d11463c74b5a0c58f/activemodel/lib/active_model/errors.rb#L85).
+If you implement accompanying getter methods, the whole data conversion would be internal only:
 
 ```ruby
-record.errors.clear
-```
+# app/models/user.rb
 
-### Custom validation errors
+class Feedback < LHS::Record
 
-In case you want to add custom validation errors to an instance of LHS::Record:
+  def ratings=(values)
+    super(
+      values.map { |k, v| { name: k, value: v } }
+    )
+  end
 
-```ruby
-user.errors.add(:name, 'The name you provided is not valid.')
+  def ratings
+    super.map { |r| [r[:name], r[:value]] }]
+  end
+end
 ```
 
-### Validation errors for nested data
+```ruby
+# app/controllers/some_controller.rb
 
-If you work with complex data structures, you sometimes need to have validation errors delegated/scoped to nested data.
+record = Record.new(ratings: { quality: 3 })
+record.ratings # {:quality=>3}
+```
 
-This also makes LHS::Records compatible with how Rails or Simpleform renders/builds forms and especially error messages.
+### Include linked resources (hyperlinks and hypermedia)
 
-```ruby
-# controller.rb
-unless @customer.save
-  @errors = @customer.errors
-end
+In a service-oriented architecture using [hyperlinks](https://en.wikipedia.org/wiki/Hyperlink)/[hypermedia](https://en.wikipedia.org/wiki/Hypermedia), records/resources can contain hyperlinks to other records/resources.
 
-# view.html
-= form_for @customer, as: :customer do |customer_form|
+When fetching records with LHS, you can specify in advance all the linked resources that you want to include in the results. 
 
-  = fields_for 'customer[:address]', @customer.address, do |address_form|
+With `includes` or `includes_all` (to enforce fetching all remote objects for paginated endpoints), LHS ensures that all matching and explicitly linked resources are loaded and merged.
 
-    = fields_for 'customer[:address][:street]', @customer.address.street, do |street_form|
+Including linked resources/records is heavily influenced by [http://guides.rubyonrails.org/active_record_class_querying](http://guides.rubyonrails.org/active_record_class_querying.html#eager-loading-associations) and you should read it to understand this feature in all it's glo
 
-      = street_form.input :name
-      = street_form.input :house_number
-```
+#### Ensure the whole linked collection is included: includes_all
 
-Would render nested forms and would also render nested form errors for nested data structures.
+In case endpoints are paginated and you are certain that you'll need all objects of a set and not only the first page/batch, use `includes_all`.
 
-You can also access those nested errors like:
+LHS will ensure that all linked resources are around by loading all pages (parallelized/performance optimized).
 
 ```ruby
-@customer.address.errors
-@customer.address.street.errors
+# app/controllers/some_controller.rb
+
+customer = Customer.includes_all(contracts: :products).find(1)
+```
+```
+> GET https://service.example.com/customers/1
+< {... contracts: { href: 'https://service.example.com/customers/1/contracts' } }
+> GET https://service.example.com/customers/1/contracts?limit=100
+< {... items: [...], limit: 10, offset: 0, total: 32 }
+In parallel: 
+  > GET https://service.example.com/customers/1/contracts?limit=10&offset=10
+  < {... products: [{ href: 'https://service.example.com/product/LBC' }] }
+  > GET https://service.example.com/customers/1/contracts?limit=10&offset=20
+  < {... products: [{ href: 'https://service.example.com/product/LBB' }] }
+In parallel:
+  > GET https://service.example.com/product/LBC
+  < {... name: 'Local Business Card' }
+  > GET https://service.example.com/product/LBB
+  < {... name: 'Local Business Basic' }
 ```
 
-### Translation of validation errors
+```ruby
+# app/controllers/some_controller.rb
 
-Just like Activerecord, LHS tries to translate validation error messages.
-If a translation exists for one of the following translation keys, LHS will take a translated error (also in the following order) rather than the plain error message/code:
+customer.contracts.length # 32
+customer.contracts.first.products.first.name # Local Business Card
 
-```ruby
-lhs.errors.records.customer.attributes.name.unsupported_property_value
-lhs.errors.records.customer.unsupported_property_value
-lhs.errors.messages.unsupported_property_value
-lhs.errors.attributes.name.unsupported_property_value
-lhs.errors.fallback_message
 ```
 
-### Know issue with `ActiveModel::Validations`
-If you are using `ActiveModel::Validations` and add errors to the LHS::Record instance - as described above - then those errors will be overwritten by the errors from `ActiveModel::Validations` when using `save`  or `valid?`. [Open issue](https://github.com/local-ch/lhs/issues/159)
-
-### Blocking errors, original "errors"
+#### Include the first linked page or single item is included: include
 
-The fact that records could have errors is not coupled to any response status code.
+`includes` includes the first page/response when loading the linked resource. **If the endpoint is paginated, only the first page will be included.**
 
-LHS makes errors accessible, if they are present:
+```ruby
+# app/controllers/some_controller.rb
 
+customer = Customer.includes(contracts: :products).find(1)
 ```
-  {
-    company_name: 'localsearch',
-    field_errors: [{
-      code: 'REQUIRED_PROPERTY_VALUE',
-      path: ['place', 'opening_hours']
-    }
-  }
 ```
-
-LHS makes those errors available when accessing `.errors`:
+> GET https://service.example.com/customers/1
+< {... contracts: { href: 'https://service.example.com/customers/1/contracts' } }
+> GET https://service.example.com/customers/1/contracts?limit=100
+< {... items: [...], limit: 10, offset: 0, total: 32 }
+In parallel:
+  > GET https://service.example.com/product/LBC
+  < {... name: 'Local Business Card' }
+  > GET https://service.example.com/product/LBB
+  < {... name: 'Local Business Basic' }
+```
 
 ```ruby
-  presence = Presence.create(
-    place: { href: 'http://storage/places/1' }
-  )
-
-  presence.errors.any? # true
-  presence.place.errors.messages[:opening_hours] # ['This field needs to be present']
-  presence.place.errors.codes[:opening_hours] # ['REQUIRED_PROPERTY_VALUE']
-```
+# app/controllers/some_controller.rb
 
-### Non blocking validation errors, so called warnings
+customer.contracts.length # 10
+customer.contracts.first.products.first.name # Local Business Card
 
-In some cases, you need non blocking meta information about potential problems with the created record, so called warnings.
+```
 
-If the API endpoint implements warnings:
+#### Include various levels of linked data
 
-```
-  {
-    field_warnings: [{
-      code: 'WILL_BE_RESIZED',
-      path: ['place', 'photos', 0],
-      message: 'The image will be resized.'
-    }
-  }
-```
+The method syntax of `includes` and `includes_all`, allows you include hyperlinks stored in deep nested data strutures:
 
-LHS makes those warnings available:
+Some examples:
 
 ```ruby
-  presence = Presence.options(params: { synchronize: false }).create(
-    place: { href: 'http://storage/places/1' }
-  )
+Record.includes(:localch_account, :entry)
+# Includes localch_account -> entry
+# { localch_account: { href: '...', entry: { href: '...' } } }
 
-  presence.warnings.any? # true
-  presence.place.photos[0].warnings.messages.first # 'The photos will be resized'
+Record.includes([:localch_account, :entry])
+# Includes localch_account and entry
+# { localch_account: { href: '...' }, entry: { href: '...' } }
+
+Record.includes(campaign: [:entry, :user])
+# Includes campaign and entry and user from campaign
+# { campaign: { href: '...' , entry: { href: '...' }, user: { href: '...' } } }
 ```
 
-Warnings behave like [Validation Errors](#Validation) and implements the same interfaces and methods.
+#### Identify and cast known records when including records
 
-## Pagination
+When including linked resources with `includes` or `includes_all`, already defined records and their endpoints and configurations are used to make the requests to fetch the additional data.
 
-LHS supports paginated APIs and it also supports various pagination strategies and by providing configuration possibilities.
+That also means that options for endpoints of linked resources are applied when requesting those in addition.
 
-LHS differentiates between the *pagination strategy* (how items/pages are navigated) itself and *pagination keys* (how stuff is named).
+This applies for example a records endpoint configuration even though it's fetched/included through another record:
 
-*Example 1 "offset"-strategy (default configuration)*
 ```ruby
-# API response
-{
-  items: [{...}, ...]
-  total: 300,
-  limit: 100,
-  offset: 0
-}
-# Next 'pages' are navigated with offset: 100, offset: 200, ...
+# app/models/favorite.rb
 
-# Nothing has to be configured in LHS because this is default pagination naming and strategy
-class Results < LHS::Record
-  endpoint 'results'
-end
-```
+class Favorite < LHS::Record
 
-*Example 2 "page"-strategy and some naming configuration*
-```ruby
-# API response
-{
-  docs: [{...}, ...]
-  totalPages: 3,
-  limit: 100,
-  page: 1
-}
-# Next 'pages' are navigated with page: 1, offset: 2, ...
+  endpoint '{+service}/users/{user_id}/favorites', auth: { basic: { username: 'steve', password: 'can' } }
+  endpoint '{+service}/users/{user_id}/favorites/:id', auth: { basic: { username: 'steve', password: 'can' } }
 
-# How LHS has to be configured
-class Results < LHS::Record
-  configuration items_key: 'docs', total_key: 'totalPages', pagination_key: 'page', pagination_strategy: 'page'
-  endpoint 'results'
 end
 ```
 
-*Example 3 "start"-strategy and naming configuration*
 ```ruby
-# API response
-{
-  results: [{...}, ...]
-  total: 300,
-  badgeSize: 100,
-  startAt: 1
-}
-# Next 'pages' are navigated with startWith: 101, startWith: 201, ...
-
-# How LHS has to be configured
-class Results < LHS::Record
-  configuration items_key: 'results', limit_key: 'badgeSize', pagination_key: 'startAt', pagination_strategy: 'start'
-  endpoint 'results'
-end
-```
+# app/models/place.rb
 
-In case of paginated resources it's important to know the difference between [count vs. length](#count-vs-length)
+class Place < LHS::Record
 
-## Configuration of Records
+  endpoint '{+service}/v2/places', auth: { basic: { username: 'steve', password: 'can' } }
+  endpoint '{+service}/v2/places/{id}', auth: { basic: { username: 'steve', password: 'can' } }
 
-```ruby
-class Search < LHS::Record
-  configuration items_key: 'searchResults', total_key: 'total', limit_key: 'limit', pagination_key: 'offset', pagination_strategy: 'offset'
-  endpoint 'https://search'
 end
 ```
 
-`item_key` key used to unwrap the actual object from within the response body.
-
-`items_key` key used to determine items of the current page (e.g. `docs`, `items`, etc.).
-
-`item_created_key` key used to merge record data thats nested in the creation response body.
-
-`limit_key` key used to work with page limits (e.g. `size`, `limit`, etc.)
+```ruby
+# app/controllers/some_controller.rb
 
-In case the `limit_key` parameter differs for where it's located in the body and how it's provided as get parameter, when retreiving pages, provide a hash with `body` and `parameter` key, to keep those two use cases separated:
+Favorite.includes(:place).where(user_id: current_user.id)
 
-```ruby
-  configuration limit_key: { body: [:response, :max], parameter: :max }
+```
+```
+> GET https://service.example.com/users/123/favorites { headers: { 'Authentication': 'Basic c3RldmU6Y2Fu' } }
+< {... items: [... { place: { href: 'https://service.example.com/place/456' } } ] }
+In parallel:
+  > GET https://service.example.com/place/456 { headers: { 'Authentication': 'Basic c3RldmU6Y2Fu' } }
+  > GET https://service.example.com/place/789 { headers: { 'Authentication': 'Basic c3RldmU6Y2Fu' } }
+  > GET https://service.example.com/place/1112 { headers: { 'Authentication': 'Basic c3RldmU6Y2Fu' } }
+  > GET https://service.example.com/place/5423 { headers: { 'Authentication': 'Basic c3RldmU6Y2Fu' } }
 ```
 
-`pagination_key` key used to paginate multiple pages (e.g. `offset`, `page`, `startAt` etc.).
+#### Apply options for requests performed to fetch included records
 
-In case the `pagination_key` parameter differs for where it's located in the body and how it's provided as get parameter, when retreiving pages, provide a hash with `body` and `parameter` key, to keep those two use cases separated:
+Use `references` to apply request options to requests performed to fetch included records:
 
 ```ruby
-  configuration pagination_key: { body: [:response, :page], parameter: :page }
+# app/controllers/some_controller.rb
+
+Favorite.includes(:place).references(place: { auth: { bearer: '123' }}).where(user_id: 1)
+```
+```
+GET https://service.example.com/users/1/favorites
+{... items: [... { place: { href: 'https://service.example.com/places/2' } }] }
+In parallel:
+  GET https://service.example.com/places/2 { headers: { 'Authentication': 'Bearer 123' } }
+  GET https://service.example.com/places/3 { headers: { 'Authentication': 'Bearer 123' } }
+  GET https://service.example.com/places/4 { headers: { 'Authentication': 'Bearer 123' } }
 ```
 
-`pagination_strategy` used to configure the strategy used for navigating (e.g. `offset`, `page`, `start`, etc.).
+### Record batch processing
 
-`total_key` key used to determine the total amount of items (e.g. `total`, `totalResults`, etc.).
+**Be careful using methods for batch processing. They could result in a lot of HTTP requests!**
 
-### Unwrap nested items
+#### all
 
-```json
-{
-  "response": {
-    "location": {
-      "id": 123
-    }
-  }
-}
-```
+`all` fetches all records from the service by doing multiple requests, best-effort parallelization, and resolving endpoint pagination if necessary:
 
 ```ruby
-class Location < LHS::Record
-  configuration item_key: [:response, :location]
-end
-
-location = Location.find(123)
-location.id # 123
+records = Record.all
 ```
-
-### Configure complex accessors for nested data
-
-If items, limit, pagination, total etc. is nested in the responding objects, use complex data structures for configuring a record.
-
 ```
-  response: {
-    offset: 0,
-    max: 50,
-    count: 1,
-    businesses: [
-      {}
-    ]
-  }
+> GET https://service.example.com/records?limit=100
+< {...
+  items: [...]
+  total: 900,
+  limit: 100,
+  offset: 0
+}
+In parallel:
+  > GET https://service.example.com/records?limit=100&offset=100
+  > GET https://service.example.com/records?limit=100&offset=200
+  > GET https://service.example.com/records?limit=100&offset=300
+  > GET https://service.example.com/records?limit=100&offset=400
+  > GET https://service.example.com/records?limit=100&offset=500
+  > GET https://service.example.com/records?limit=100&offset=600
+  > GET https://service.example.com/records?limit=100&offset=700
+  > GET https://service.example.com/records?limit=100&offset=800
 ```
 
+`all` is chainable and has the same interface like `where`:
+
 ```ruby
-  class Business < LHS::Record
-    configuration items_key: [:response, :businesses], limit_key: [:response, :max], pagination_key: [:response, :offset], total_key: [:response, :count], pagination_strategy: :offset
-    endpoint 'http://uberall/businesses'
-  end
+Record.where(color: 'blue').all
+Record.all.where(color: 'blue')
+Record.all(color: 'blue')
 ```
 
-If record data after creation is nested in the response body, configure the record, so that it gets properl merged with the your record instance:
-
-```
-POST /businesses
-  response: {
-    business: {
-      id: 123
-    }
-  }
-```
+All three are doing the same thing: fetching all records with the color 'blue' from the endpoint while resolving pagingation if endpoint is paginated.
 
-```ruby
-  class Business < LHS::Record
-    configuration item_created_key: [:response, :business]
-    endpoint 'http://uberall/businesses'
-  end
+##### Using all, when endpoint does not implement response pagination meta data
 
-  business = Business.create(name: 'localsearch')
-  business.id # 123
-```
+In case an API does not provide pagination information in the repsponse data (limit, offset and total), LHS keeps on loading pages when requesting `all` until the first empty page responds.
 
-### Pagination Chains
+#### find_each
 
-You can use chainable pagination in combination with query chains:
+`find_each` is a more fine grained way to process single records that are fetched in batches.
 
 ```ruby
-  class Record < LHS::Record
-    endpoint ':service/records'
-  end
-  Record.page(3).per(20).where(color: 'blue')
-  # /records?offset=40&limit=20&color=blue
+Record.find_each(start: 50, batch_size: 20, params: { has_reviews: true }) do |record|
+  # Iterates over each record. Starts with record no. 50 and fetches 20 records each batch.
+  record
+  break if record.some_attribute == some_value
+end
 ```
 
-The applied pagination strategy depends on the actual configured pagination, so the interface is the same for all strategies:
+#### find_in_batches
 
-```ruby
-  class Record < LHS::Record
-    endpoint '{+service}/records'
-    configuration pagination_strategy: 'page'
-  end
-  Record.page(3).per(20).where(color: 'blue')
-  # /records?page=3&limit=20&color=blue
-```
+`find_in_batches` is used by `find_each` and processes batches.
 
 ```ruby
-  class Record < LHS::Record
-    endpoint '{+service}/records'
-    configuration pagination_strategy: 'start'
-  end
-  Record.page(3).per(20).where(color: 'blue')
-  # /records?start=41&limit=20&color=blue
+Record.find_in_batches(start: 50, batch_size: 20, params: { has_reviews: true }) do |records|
+  # Iterates over multiple records (batch size is 20). Starts with record no. 50 and fetches 20 records each batch.
+  records
+  break if records.first.name == some_value
+end
 ```
 
-`limit(argument)` is an alias for `per(argument)`. Take notice that `limit` without argument instead, makes the query resolve and provides the current limit from the responds.
+### Convert/Cast specific record types: becomes
 
-### Partial Kaminari support
+Based on [ActiveRecord's implementation](http://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-becomes), LHS implements `becomes`, too.
 
-LHS implements an interface that makes it partially working with Kaminari.
+It's a way to convert records of a certain type A to another certain type B.
 
-The kaminari’s page parameter is in params[:page]. For example, you can use kaminari to render paginations based on LHS Records. Typically, your code will look like this:
+_NOTE: RPC-style actions, that are discouraged in REST anyway, are utilizable with this functionality, too. See the following example:_
 
 ```ruby
-# controller
-@items = Record.page(params[:page]).per(100)
-```
+# app/models/location.rb
 
-```ruby
-# view
-= paginate @items
+class Location < LHS::Record
+  endpoint '{+service}/locations'
+  endpoint '{+service}/locations/{id}'
+end
 ```
 
-### Pagination Links
+```ruby
+# app/models/synchronization.rb
 
-When endpoints provide indicators for current page position with links (like `next` and `previous`), LHS provides some functionalities to interact/use those links/information:
+class Synchronization < LHS::Record
+  endpoint '{+service}/locations/{id}/sync'
+end
+```
 
-`next?` Tells you if there is a next link or not.
+```ruby
+# app/controllers/some_controller.rb
 
-`previous?` Tells you if there is a previous link or not.
+location = Location.find(1)
+```
+```
+GET https://service.example.com/location/1
+```
 
+```ruby
+# app/controllers/some_controller.rb
 
-## Automatic Detection of Collections
+synchronization = location.becomes(Synchronization)
+synchronization.save!
+```
+```
+POST https://service.example.com/location/1/sync { body: '{ ... }' }
+```
 
-How to configure endpoints for automatic collection detection?
+## Request Cycle Cache
 
-LHS detects automatically if the responded data is a single business object or a set of business objects (collection).
+By default, LHS does not perform the same http request multiple times during one request/response cycle.
 
-Conventionally, when the responds contains an `items` key `{ items: [] }` it's treated as a collection, but also if the responds contains a plain raw array: `[{ href: '' }]` it's also treated as a collection.
+```ruby
+# app/models/user.rb
 
-In case the responds uses another key than `items`, you can configure it within an `LHS::Record`:
+class User < LHS::Record
+  endpoint '{+service}/users/{id}'
+end
+```
 
 ```ruby
-class Results < LHS::Record
-  configuration items_key: 'docs'
+# app/models/location.rb
+
+class Location < LHS::Record
+  endpoint '{+service}/locations/{id}'
 end
 ```
 
-## form_for Helper
-Rails `form_for` view-helper can be used in combination with instances of LHS::Record to autogenerate forms:
 ```ruby
-<%= form_for(@instance, url: '/create') do |f| %>
-  <%= f.text_field :name %>
-  <%= f.text_area :text %>
-  <%= f.submit "Create" %>
-<% end %>
+# app/controllers/some_controller.rb
+
+def index
+  @user = User.find(1)
+  @locations = Location.includes(:owner).find(2)
+end
+```
+```
+GET https://service.example.com/users/1
+GET https://service.example.com/location/2
+{... owner: { href: 'https://service.example.com/users/1' } }
+From cache:
+  GET https://service.example.com/users/1
 ```
 
-## Count vs. Length
+It uses the [LHC Caching Interceptor](https://github.com/local-ch/lhc#caching-interceptor) as caching mechanism base and sets a unique request id for every request cycle with Railties to ensure data is just cached within one request cycle and not shared with other requests.
 
-The behavior of `count` and `length` is based on ActiveRecord's behavior.
+Only GET requests are considered for caching by using LHC Caching Interceptor's `cache_methods` option internally and considers request headers when caching requests, so requests with different headers are not served from cache.
 
-`count` Determine the number of elements by taking the number of total elements that is provided by the endpoint/api.
+The LHS Request Cycle Cache is opt-out, so it's enabled by default and will require you to enable the [LHC Caching Interceptor](https://github.com/local-ch/lhc#caching-interceptor) in your project.
 
-`length` This returns the number of elements loaded from an endpoint/api. In case of paginated resources this can be different to count, as it depends on how many pages have been loaded.
+### Change store for LHS' request cycle cache
 
-## Inheritance
+By default the LHS Request Cycle Cache will use `ActiveSupport::Cache::MemoryStore` as its cache store. Feel free to configure a cache that is better suited for your needs by:
 
-You can inherit from previously defined records and also inherit endpoints that way:
+```ruby
+# config/initializers/lhc.rb
 
-```
-class Base < LHS::Record
-  endpoint 'records/{id}'
+LHC.configure do |config|
+  config.request_cycle_cache = ActiveSupport::Cache::MemoryStore.new
 end
+```
 
-class Example < Base
-end
+### Disable request cycle cache
+
+If you want to disable the LHS Request Cycle Cache, simply disable it within configuration:
+
+```ruby
+# config/initializers/lhc.rb
 
-Example.find(1) # GET records/1
+LHC.configure do |config|
+  config.request_cycle_cache_enabled = false
+end
 ```
 
-## Testing: How to write tests when using LHS
+## Testing with LHS
 
-[WebMock](https://github.com/bblimke/webmock)!
+**Best practice in regards of testing applications using LHS, is to let LHS fetch your records, actually perform HTTP requests and [WebMock](https://github.com/bblimke/webmock) to stub/mock those http requests/responses.**
 
-Best practice is to let LHS fetch your records and Webmock to stub/mock endpoints responses.
-This follows the [Black Box Testing](https://en.wikipedia.org/wiki/Black-box_testing) approach and prevents you from building up constraints to LHS' internal structures/mechanisms, which will break when we change internal things.
-LHS provides interfaces that result in HTTP requests, this is what you should test.
+This follows the [Black Box Testing](https://en.wikipedia.org/wiki/Black-box_testing) approach and prevents you from creating constraints to LHS' internal structures and mechanisms, which will break as soon as we change internals.
 
 ```ruby
+# specs/*/some_spec.rb 
+
 let(:contracts) do
   [
     {number: '1'},
@@ -1386,8 +2221,8 @@ let(:contracts) do
   ]
 end
 
-before(:each) do
-  stub_request(:get, "http://datastore/user/:id/contracts")
+before do
+  stub_request(:get, "https://service.example.com/contracts")
     .to_return(
       body: {
         items: contracts,
@@ -1406,29 +2241,43 @@ it 'displays contracts' do
 end
 ```
 
-## Test support (caching)
+### Test helper for request cycle cache
 
-Add to your spec_helper.rb:
+In order to not run into caching issues during your tests, when (request cycle cache)[#request-cycle-cache] is enabled, simply require the following helper in your tests:
 
 ```ruby
-  require 'lhs/test/request_cycle_cache_helper'
+# spec/spec_helper.rb
+
+require 'lhs/test/request_cycle_cache_helper'
 ```
 
 This will initialize a MemoryStore cache for LHC::Caching interceptor and resets the cache before every test.
 
-## Where values hash
+### Test query chains
+
+#### By explicitly resolving the chain: fetch
 
-Returns a hash of where conditions.
-Common to use in tests, as where queries are not performing any HTTP-requests when no data is accessed.
+Use `fetch` in tests to resolve chains in place and expect WebMock stubs to be requested.
 
 ```ruby
+# specs/*/some_spec.rb 
+
 records = Record.where(color: 'blue').where(available: true).where(color: 'red')
 
 expect(
-  records
+  records.fetch
 ).to have_requested(:get, %r{records/})
   .with(query: hash_including(color: 'blue', available: true))
-# will fail as no http request is made (no data requested)
+```
+
+#### Without resolving the chain: where_values_hash
+
+As `where` chains are not resolving to HTTP-requests when no data is accessed, you can use `where_values_hash` to access the values that would be used to resolve the chain, and test those:
+
+```ruby
+# specs/*/some_spec.rb 
+
+records = Record.where(color: 'blue').where(available: true).where(color: 'red')
 
 expect(
   records.where_values_hash
@@ -1438,3 +2287,4 @@ expect(
 ## License
 
 [GNU Affero General Public License Version 3.](https://www.gnu.org/licenses/agpl-3.0.en.html)
+