flexirest 1.6.5 → 1.6.6

data/docs/httpparse-error-handling.md

@@ -0,0 +1,17 @@
+# *Flexirest:* HTTP/parse error handling
+
+Sometimes the backend server may respond with a non-200/304 header, in which case the code will raise an `Flexirest::HTTPClientException` for 4xx errors or an `Flexirest::HTTPServerException` for 5xx errors. These both have a `status` accessor and a `result` accessor (for getting access to the parsed body):
+
+```ruby
+begin
+  Person.all
+rescue Flexirest::HTTPClientException, Flexirest::HTTPServerException => e
+  Rails.logger.error("API returned #{e.status} : #{e.result.message}")
+end
+```
+
+If the response is unparsable (e.g. not in the desired content type), then it will raise an `Flexirest::ResponseParseException` which has a `status` accessor for the HTTP status code and a `body` accessor for the unparsed response body.
+
+-----
+
+[< Updating only changed/dirty attributes](updating-only-changed-dirty-attributes.md) | [Validation >](validation.md)

data/{CONTRIBUTING.md → docs/internals.md}

@@ -1,19 +1,17 @@
-# Flexirest (ARC) Contributing Guide
+# *Flexirest:* Internals of Flexirest
 
 ## Introduction
 
-This project was built at Which? Ltd in the UK as ActiveRestClient, but was released as open source in 2014 under the MIT Licence.  This is Andy Jeffries' fork of the project as the original seems not to be maintained by Which? and there's been no communication back about the project.
-
 We're happy to receive contributions from the community for features and bugfixes and hopefully this guide helps new developers to the project to understand how to get started with the internals of Flexirest.
 
 ## Overview
 
-![Component Overview Diagram](https://raw.githubusercontent.com/andyjeffries/flexirest/master/docs/Flexirest%20Internals.png)
+![Component Overview Diagram](Flexirest%20Internals.png)
 
 ## Components
 
 ### Base
-The main class in ARC is `Flexirest::Base`.  This includes a number of modules to provide a basic object ready to inherit from to form your own API classes.
+The main class in Flexirest is `Flexirest::Base`.  This includes a number of modules to provide a basic object ready to inherit from to form your own API classes.
 
 **Configuration** includes all of the functionality for class and library level configuration (base_url, verbose logging, request format, etc).
 
@@ -33,7 +31,7 @@ This is a simple class that either uses a plain text file or Rails' logger if be
 
 ### Connection Manager/Connection
 
-The principle is that ARC keeps a cached `Connection` to each unique API server and these are kept open using [persistent connections](https://en.wikipedia.org/wiki/HTTP_persistent_connection).  The connection for a given `base_url` is created or retrieved from the pool by the `ConnectionManager`.
+The principle is that Flexirest keeps a cached `Connection` to each unique API server and these are kept open using [persistent connections](https://en.wikipedia.org/wiki/HTTP_persistent_connection).  The connection for a given `base_url` is created or retrieved from the pool by the `ConnectionManager`.
 
 ### Request
 

data/docs/json-api.md

@@ -0,0 +1,42 @@
+# *Flexirest:* JSON API
+
+If you are working with a [JSON API](http://jsonapi.org), you need to activate JSON API by specifying the `json_api` proxy:
+
+```ruby
+class Article < Flexirest::Base
+  proxy :json_api
+end
+```
+
+This proxy translates requests according to the JSON API specifications, parses responses, and retrieves linked resources. It also adds the `Accept: application/vnd.api+json` header for all requests.
+
+It supports lazy loading by default. Unless a compound document is returned from the connected JSON API service, it will make another request to the service for the specified linked resource.
+
+To reduce the number of requests to the service, you can ask the service to include the linked resources in the response. Such responses are called "compound documents". To do this, use the `includes` method:
+
+```ruby
+# Makes a call to /articles with parameters: include=images
+Article.includes(:images).all
+
+# For nested resources, the include parameter becomes: include=images.tags,images.photographer
+Article.includes(:images => [:tags, :photographer]).all
+```
+
+For POST and PATCH requests, the proxy formats a JSON API compliant request, and adds a `Content-Type: application/vnd.api+json` header. It guesses the `type` value in the resource object from the class name, but it can be set specifically with `alias_type`:
+
+```ruby
+class Photographer < Flexirest::Base
+  proxy :json_api
+  # Sets the type in the resource object to "people"
+  alias_type :people
+
+  patch :update, '/photographers/:id'
+end
+```
+
+NB: Updating relationships is not yet supported.
+
+
+-----
+
+[< Plain requests](plain-requests.md) | [Proxying APIs >](proxying-apis.md)

data/docs/lazy-loading.md

@@ -0,0 +1,31 @@
+# *Flexirest:* Lazy loading
+
+Flexirest supports lazy loading (delaying the actual API call until the response is actually used, so that views can be cached without still causing API calls).
+
+**Note: Currently this isn't enabled by default, but this is likely to change in the future to make lazy loading the default.**
+
+To enable it, simply call the lazy_load! method in your class definition:
+
+```ruby
+class Article < Flexirest::Base
+  lazy_load!
+end
+```
+
+If you have a ResultIterator that has multiple objects, each being lazy loaded or HAL linked resources that isn't loaded until it's used, you can actually parallelise the fetching of the items using code like this:
+
+```ruby
+items.parallelise(:id)
+
+# or
+
+items.parallelise do |item|
+  item.id
+end
+```
+
+This will return an array of the named method for each object or the response from the block and will have loaded the objects in to the resource.
+
+-----
+
+[< Using callbacks](using-callbacks.md) | [Authentication >](authentication.md)

data/{Migrating-from-ActiveRestClient.md → docs/migrating-from-activerestclient.md}

@@ -1,4 +1,4 @@
-# Migrating from ActiveRestClient
+# *Flexirest:* Migrating from ActiveRestClient
 
 While contracting at Which? Ltd I wrote a library in Ruby to access REST APIs in a very flexible, almost ActiveRecord style. This was agreed (after long discussions with the legal department) to be released as open source.
 
@@ -30,4 +30,4 @@ The second step is to find and replace across your codebase all instances of `Ac
 
 The third and final step is to clear your Rails cache. The easiest way of doing this is to type `Rails.cache.clear` in a Rails console.
 
-That's it, you've now switched over to Flexirest with a)lots of bug fixes, b)support for PATCH requests and c)someone actively continuing to support it!
+That's it, you've now switched over to Flexirest with a)lots of bug fixes, b)support for PATCH requests and c)someone actively continuing to support it!

data/docs/parallel-requests.md

@@ -0,0 +1,28 @@
+# *Flexirest:* Parallel requests
+
+Sometimes you know you will need to make a bunch of requests and you don't want to wait for one to finish to start the next. When using parallel requests there is the potential to finish many requests all at the same time taking only as long as the single longest request. To use parallel requests you will need to set Flexirest to use a Faraday adapter that supports parallel requests [(such as Typhoeus)](https://github.com/lostisland/faraday/wiki/Parallel-requests).
+
+```ruby
+# Set adapter to Typhoeus to use parallel requests
+Flexirest::Base.adapter = :typhoeus
+```
+
+Now you just need to get ahold of the connection that is going to make the requests by specifying the same host that the models will be using. When inside the `in_parallel` block call request methods as usual and access the results after the `in_parallel` block ends.
+
+```ruby
+Flexirest::ConnectionManager.in_parallel('https://www.example.com') do
+    @person = Person.find(1234)
+    @employers = Employer.all
+
+    puts @person #=> nil
+    puts @employers #=> nil
+end # The requests are all fired in parallel during this end statement
+
+puts @person.name #=> "John"
+puts @employers.size #=> 7
+```
+
+
+-----
+
+[< Body types](body-types.md) | [Faking calls >](faking-calls.md)

data/docs/per-request-parameter-encoding.md

@@ -0,0 +1,32 @@
+# *Flexirest:* Per-request parameter encoding
+
+When URL-encoding GET parameters, Rudy adds brackets(`[]`) by default to any parameters in an `Array`. For example, if you tried to pass these parameters:
+
+```ruby
+Person.all(param: [1, 2, 3])
+```
+
+Ruby would encode the URL as
+
+```
+?param[]=1&param[]=2&param[]=3
+```
+
+If you prefer flattened notation instead, pass a `params_encoder` option of `:flat` when mapping the call. So this call:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', params_encoder: :flat
+end
+```
+
+would output the following URL:
+
+```
+?param=1&param=2&param=3
+```
+
+
+-----
+
+[< Per-request timeouts](per-request-timeouts.md) | [Automatic conversion of fields to Date/DateTime >](automatic-conversion-of-fields-to-datedatetime.md)

data/docs/per-request-timeouts.md

@@ -0,0 +1,13 @@
+# *Flexirest:* Per-request timeouts
+
+There are times when an API is generally quick, but one call is very intensive. You don't want to set a global timeout in the Faraday configuration block, you just want to increase the timeout for this single call. To do this, you can simply pass a `timeout` option when mapping the call containing the response (in seconds).
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', timeout: 5
+end
+```
+
+-----
+
+[< Faking calls](faking-calls.md) | [Per-request parameter encoding >](per-request-parameter-encoding.md)

data/docs/plain-requests.md

@@ -0,0 +1,30 @@
+# *Flexirest:* Plain requests
+
+If you are already using Flexirest but then want to simply call a normal URL and receive the resulting content as a string (i.e. not going through JSON parsing or instantiating in to a `Flexirest::Base` descendent) you can use code like this:
+
+```ruby
+class Person < Flexirest::Base
+end
+
+people = Person._plain_request('http://api.example.com/v1/people') # Defaults to get with no parameters
+# people is a normal Flexirest object, implementing iteration, HAL loading, etc.
+
+Person._plain_request('http://api.example.com/v1/people', :post, {id:1234,name:"John"}) # Post with parameters
+```
+
+The parameters are the same as for `_request`, but it does no parsing on the response
+
+You can also bypass the response parsing using a mapped method like this:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, "/v1/people", plain: true
+end
+```
+
+The response of a plain request (from either source) is a `Flexirest::PlainResponse` which acts like a string containing the response's body, but it also has a `_headers` method that returns the HTTP response headers and a `_status` method containing the response's HTTP method.
+
+
+-----
+
+[< Raw requests](raw-requests.md) | [JSON API >](json-api.md)

data/docs/proxying-apis.md

@@ -0,0 +1,86 @@
+# *Flexirest:* Proxying APIs
+
+Sometimes you may be working with an old API that returns JSON in a less than ideal format or the URL or parameters required have changed.
+
+If it's simply that you want attribute names like `SomeName` or `someName` to be more Ruby-style `some_name` then you can simply do that by setting `:rubify_names` when mapping an API call.
+
+```ruby
+class Article < Flexirest::Base
+  base_url "http://www.example.com"
+
+  get :all, "/all", rubify_names: true
+end
+```
+
+In more complex cases you can define a descendent of `Flexirest::ProxyBase`, pass it to your model as the proxy and have it rework URLs/parameters on the way out and the response on the way back in (already converted to a Ruby hash/array). By default any non-proxied URLs are just passed through to the underlying connection layer. For example:
+
+```ruby
+class ArticleProxy < Flexirest::ProxyBase
+  get "/all" do
+    url "/all_people" # Equiv to url.gsub!("/all", "/all_people") if you wanted to keep params
+    response = passthrough
+    translate(response) do |body|
+      body["first_name"] = body.delete("fname")
+      body
+    end
+  end
+end
+
+class Article < Flexirest::Base
+  proxy ArticleProxy
+  base_url "http://www.example.com"
+
+  get :all, "/all", fake:"{\"name\":\"Billy\"}"
+  get :list, "/list", fake:"[{\"name\":\"Billy\"}, {\"name\":\"John\"}]"
+end
+
+Article.all.first_name == "Billy"
+```
+
+This example does two things:
+
+1. It rewrites the incoming URL for any requests matching "_/all_" to "/all_people"
+2. It uses the `translate` method to move the "fname" attribute from the response body to be called "first_name". The translate method must return the new object at the end (either the existing object alterered, or a new object to replace it with)
+
+As the comment shows, you can use `url value` to set the request URL to a particular value, or you can call `gsub!` on the url to replace parts of it using more complicated regular expressions.
+
+You can use the `get_params` or `post_params` methods within your proxy block to amend/create/delete items from those request parameters, like this:
+
+```ruby
+get "/list" do
+  get_params["id"] = get_params.delete("identifier")
+  passthrough
+end
+```
+
+This example renames the get_parameter for the request from `identifier` to `id` (the same would have worked with post_params if it was a POST/PUT request). The `passthrough` method will take care of automatically recombining them in to the URL or encoding them in to the body as appropriate.
+
+If you want to manually set the body for the API yourself you can use the `body` method
+
+```ruby
+put "/update" do
+  body "{\"id\":#{post_params["id"]}}"
+  passthrough
+end
+```
+
+This example takes the `post_params["id"]` and converts the body from being a normal form-encoded body in to being a JSON body.
+
+The proxy block expects one of three things to be the return value of the block.
+
+1. The first options is that the call to `passthrough` is the last thing and it calls down to the connection layer and returns the actual response from the server in to the "API->Object" mapping layer ready for use in your application
+2. The second option is to save the response from `passthrough` and use `translate` on it to alter the structure.
+3. The third option is to use `render` if you want to completely fake an API and return the JSON yourself
+
+To completely fake the API, you can do the following. Note, this is also achievable using the `fake` setting when mapping a method, however by doing it in a Proxy block means you can dynamically generate the JSON rather than just a hard coded string.
+
+```ruby
+put "/fake" do
+  render "{\"id\":1234}"
+end
+```
+
+
+-----
+
+[< JSON API](json-api.md) | [Translating APIs >](translating-apis.md)

data/docs/raw-requests.md

@@ -0,0 +1,38 @@
+# *Flexirest:* Raw requests
+
+Sometimes you have have a URL that you just want to force through, but have the response handled in the same way as normal objects or you want to have the callbacks run (say for authentication). The easiest way to do that is to call `_request` on the class:
+
+```ruby
+class Person < Flexirest::Base
+end
+
+people = Person._request('http://api.example.com/v1/people') # Defaults to get with no parameters
+# people is a normal Flexirest object, implementing iteration, HAL loading, etc.
+
+Person._request('http://api.example.com/v1/people', :post, {id:1234,name:"John"}) # Post with parameters
+```
+
+When you need to specify custom headers (for example for authentication) you can do this with a fourth option to the `_request` method. If you are using the default paramaters you'll need to specify them. For example:
+
+```ruby
+Person._request("http://api.example.com/v1/people", :get, {}, {headers:{"X-Something": "foo/bar"}})
+```
+
+If you want to use a lazy loaded request instead (so it will create an object that will only call the API if you use it), you can use `_lazy_request` instead of `_request`. If you want you can create a construct that creates and object that lazy loads itself from a given method (rather than a URL):
+
+```ruby
+@person = Person._lazy_request(Person._request_for(:find, 1234))
+```
+
+This initially creates a `Flexirest::Request` object as if you'd called `Person.find(1234)` which is then passed in to the `_lazy_request` method to return an object that will call the request if any properties are actually used. This may be useful at some point, but it's actually easier to just prefix the `find` method call with `lazy_` like:
+
+```ruby
+@person = Person.lazy_find(1234)
+```
+
+Doing this will try to find a literally mapped method called "lazy_find" and if it fails, it will try to use "find" but instantiate the object lazily.
+
+
+-----
+
+[< Automatic conversion of fields to Date/DateTime](automatic-conversion-of-fields-to-datedatetime.md) | [Plain requests >](plain-requests.md)

data/docs/required-parameters.md

@@ -0,0 +1,17 @@
+# *Flexirest:* Required parameters
+
+If you want to specify that certain parameters are required for a specific call, you can specify them like:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', :requires => [:active]
+end
+
+@people = Person.all # raises Flexirest::MissingParametersException
+@people = Person.all(active:false)
+```
+
+
+-----
+
+[< Root elements](root-elements.md) | [Updating only changed/dirty attributes >](updating-only-changed-dirty-attributes.md)

data/docs/root-elements.md

@@ -0,0 +1,34 @@
+# *Flexirest:* Root elements
+
+If your response comes back with a root node and you'd like to ignore it, you can define the mapping as:
+
+```ruby
+class Feed < Flexirest::Base
+  post :list, "/feed", ignore_root: "feed"
+end
+```
+
+Alternatively if you want to wrap your JSON request body in a root element, e.g.:
+
+```json
+{
+  "feed": {
+    "id": 1
+  }
+}
+```
+
+You can do it like this:
+
+```ruby
+class Feed < Flexirest::Base
+  post :list, "/feed", wrap_root: "feed"
+end
+
+Feed.list(id: 1)
+```
+
+
+-----
+
+[< Default parameters](default-parameters.md) | [Required parameters >](required-parameters.md)

data/{Ruby-on-Rails-Integration.md → docs/ruby-on-rails-integration.md}

@@ -1,7 +1,6 @@
-# Ruby on Rails Integration
-
-Flexirest works fine with Ruby on Rails Framework. This guide was tested with a Rails 4.2.x Application.
+# *Flexirest:* Ruby on Rails Integration
 
+The author built Flexirest to use within Ruby on Rails, but it doesn't require full Ruby on Rails. This guide was tested with a Rails 4.2.x Application but also works fine with Rails 5.x.
 
 ## Integration
 
@@ -15,9 +14,9 @@ gem 'flexirest'
 
 ## Configuration
 
-It's possible to explicit specify the `base_url` in the Model Class. If you have an common API Endpoint it makes sense to setup an initializer in `config/initializers` or use the `Rails.application.configure` namespace.
+It's possible to explicit specify the `base_url` in the model class. If you have an common API Endpoint it makes sense to setup an initializer in `config/initializers` or use the `Rails.configuration.x` namespace.
 
-This example use a custom file in `config/initializers` to setup the API endpoint. Either set a fixed URL or use environment variables if you would like to follow the [12factor](http://12factor.net/config) rules for preparing your application running on cloud infrastructure like heroku.
+This example use a custom file in `config/initializers` to setup the API endpoint. Either set a fixed URL or use environment variables if you would like to follow the [12factor](http://12factor.net/config) rules for preparing your application running on cloud infrastructure like Heroku, Kubernetes or Docker Swarm.
 
 ```ruby
 # config/initializers/flexirest.rb
@@ -41,17 +40,19 @@ end
 
 ## Model
 
-The `ActiveModel` shortcuts will add support for `form_for` helper and `@person.errors` functionally in your views.
-For example, if you have a scaffolded view structure this will just work out of the box. Read more about `ActiveModel` here:
+The `ActiveModel` shortcuts will add support for `form_for` helper and `@person.errors` functionally in your views. For example, if you have a scaffolded view structure this will just work out of the box.
+
+Read more about `ActiveModel` here:
 
  * [ActiveModel::Naming](http://api.rubyonrails.org/classes/ActiveModel/Naming.html)
  * [ActiveModel::Conversion](http://api.rubyonrails.org/classes/ActiveModel/Conversion.html)
  * [ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations.html)
 
 In Rails, a resourceful route provides a mapping between HTTP verbs and URLs to controller actions.
+
 Add the GET, POST, PATCH and DELETE methods that reflect to your endpoint.
 
-Add the `persisted?` method to your Class to support Rails named_routes, so you could use `edit_person_path(person)` without explicit pass the `person.id`.
+Add the `persisted?` method to your Class to support Rails' `named_routes`, so you could use `edit_person_path(person)` without explicitly passing the `person.id`.
 
 
 ```ruby
@@ -78,11 +79,9 @@ end
 
 ## Controller
 
-The Controller is structured like an standard RESTful Rails Controller. Only the `update` method has
-a small change about how params getting processed.
+The Controller is structured like an standard RESTful Rails Controller. Only the `update` method has a small change about how params getting processed.
 
-Flexirest requires the `id` inside the params hash, this is not included by default.
-Easily merge the current id into the params with `person_params.merge(id: @person.id)`
+Flexirest requires the `id` inside the params hash, this is not included by default. Easily merge the current `id` into the parameters with `person_params.merge(id: @person.id)`
 
 No other changes had to be made for the controller.
 
@@ -140,3 +139,8 @@ class PeopleController < ApplicationController
     end
 end
 ```
+
+
+-----
+
+[< Basic usage](basic-usage.md) | [Faraday configuration >](faraday-configuration.md)

data/docs/translating-apis.md

@@ -0,0 +1,31 @@
+# *Flexirest:* Translating APIS (DEPRECATED)
+
+**IMPORTANT: This functionality has been deprecated in favour of the [Proxying APIs](proxying-apis.md) functionality. You should aim to remove this from your code as soon as possible.**
+
+Sometimes you may be working with an API that returns JSON in a less than ideal format. In this case you can define a barebones class and pass it to your model. The Translator class must have class methods that are passed the JSON object and should return an object in the correct format. It doesn't need to have a method unless it's going to translate that mapping though (so in the example below there's no list method). For example:
+
+```ruby
+class ArticleTranslator
+  def self.all(object)
+    ret = {}
+    ret["first_name"] = object["name"]
+    ret
+  end
+end
+
+class Article < Flexirest::Base
+  translator ArticleTranslator
+  base_url "http://www.example.com"
+
+  get :all, "/all", fake:"{\"name\":\"Billy\"}"
+  get :list, "/list", fake:"[{\"name\":\"Billy\"}, {\"name\":\"John\"}]"
+end
+
+Article.all.first_name == "Billy"
+```
+
+
+
+-----
+
+[< Proxying APIs](proxying-apis.md) | [Default parameters >](default-parameters.md)

data/docs/updating-only-changed-dirty-attributes.md

@@ -0,0 +1,37 @@
+# *Flexirest:* Updating only changed/dirty attributes
+
+The most common RESTful usage of the PATCH http-method is to only send fields that have changed. The default action for all calls is to send all known object attributes for POST/PUT/PATCH calls, but this can be altered by setting the `only_changed` option on your call declaration.
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people'
+  patch :update, '/people/:id', :only_changed => true # only send attributes that are changed/dirty
+end
+
+person = Person.all.first
+person.first_name = 'Billy'
+person.update # performs a PATCH request, sending only the now changed 'first_name' attribute
+```
+
+This functionality is per-call, and there is some additional flexibility to control which attributes are sent and when.
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people'
+  patch :update_1, '/people/:id', :only_changed => true # only send attributes that are changed/dirty (all known attributes on this object are subject to evaluation)
+  patch :update_2, "/people/:id", :only_changed => [:first_name, :last_name, :dob] # only send these listed attributes, and only if they are changed/dirty
+  patch :update_3, "/people/:id", :only_changed => {first_name: true, last_name: true, dob: false} # include the listed attributes marked 'true' only when changed; attributes marked 'false' are always included (changed or not, and if not present will be sent as nil); unspecified attributes are never sent
+end
+```
+
+#### Additional Notes:
+
+- The above examples specifically showed PATCH methods, but this is also available for POST and PUT methods for flexibility purposes (even though they break typical REST methodology).
+- This logic is currently evaluated before Required Parameters, so it is possible to ensure that requirements are met by some clever usage.
+
+  - This means that if a method is `:requires => [:active], :only_changed => {active: false}` then `active` will always have a value and would always pass the `:requires` directive (so you need to be very careful because the answer may end up being `nil` if you didn't specifically set it).
+
+
+-----
+
+[< Required parameters](required-parameters.md) | [HTTP/parse error handling >](httpparse-error-handling.md)