flexirest 1.6.5 → 1.6.6

data/docs/associations.md

@@ -0,0 +1,181 @@
+# *Flexirest:* Associations
+
+There are two types of association. One assumes when you call a method you actually want it to call the method on a separate class (as that class has other methods that are useful). The other is lazy loading related classes from a separate URL.
+
+## Type 1 - Loading Other Classes
+
+If the call would return a single instance or a list of instances that should be considered another object, you can also specify this when mapping the method using the `:has_one` or `:has_many` options respectively. It doesn't call anything on that object except for instantiate it, but it does let you have objects of a different class to the one you initially called.
+
+```ruby
+class Expense < Flexirest::Base
+  def inc_vat
+    ex_vat * 1.20
+  end
+end
+
+class Address < Flexirest::Base
+  def full_string
+    "#{self.street}, #{self.city}, #{self.region}, #{self.country}"
+  end
+end
+
+class Person < Flexirest::Base
+  get :find, "/people/:id", :has_many => {:expenses => Expense}, 
+    :has_one => {:address => Address}
+end
+
+@person = Person.find(1)
+puts @person.expenses.reduce {|e| e.inc_vat}
+puts @person.address.full_string
+```
+
+You can also use `has_one`/`has_many` on the class level to allow chaining of classes. You can specify the class name or allow the system to automatically convert it to the singular class. For example:
+
+```ruby
+class Expense < Flexirest::Base
+  def inc_vat
+    ex_vat * 1.20
+  end
+end
+
+class Address < Flexirest::Base
+  def full_string
+    "#{self.street}, #{self.city}, #{self.region}, #{self.country}"
+  end
+end
+
+class Person < Flexirest::Base
+  has_one :addresses
+  has_many :expenses, Expense
+  get :find, "/people/:id"
+end
+
+class Company < Flexirest::Base
+  has_many :people
+  get :find, "/companies/:id"
+end
+```
+
+Sometimes we want attributes to just return a simple Ruby Array. To achieve this we can add an `:array` option to the method. This is especially useful when the attribute contains an array of scalar values. If you don't specify the `:array` option Flexirest will return a `Flexirest::ResultIterator`. To illustrate the difference consider the following example:
+
+```ruby
+class Book < Flexirest::Base
+  # :authors attribute ["Robert T. Kiyosaki", "Sharon L. Lechter C.P.A"]
+  # :genres attribute ["self-help", "finance", "education"]
+  get :find, "/books/:name", array: [:authors]
+end
+```
+
+In the example above, the following results can be observed:
+
+```ruby
+@book = Book.find("rich-dad-poor-dad")
+puts @book.authors
+#=> ["Robert T. Kiyosaki", "Sharon L. Lechter C.P.A"]
+puts @book.authors.class
+#=> Array
+puts @book.genres
+#=> #<Flexirest::ResultIterator:0x007ff420fe7a88 @_status=nil, @_headers=nil, @items=["self-help", "finance", "education"]>
+puts @books.genres.class
+#=> Flexirest::ResultIterator
+puts @books.genres.items
+#=> ["self-help", "finance", "education"]
+```
+
+When the `:array` option includes an attribute, it is assumed the values were returned with the request, and they will not be lazily loaded. It is also assumed the attribute values do not map to a Flexirest resource.
+
+## Type 2 - Lazy Loading From Other URLs
+
+When mapping the method, passing a list of attributes will cause any requests for those attributes to mapped to the URLs given in their responses. The response for the attribute may be one of the following:
+
+```ruby
+"attribute" : "URL"
+"attribute" : ["URL", "URL"]
+"attribute" : { "url" : "URL"}
+"attribute" : { "href" : "URL"}
+"attribute" : { "something" : "URL"}
+```
+
+The difference between the last 3 examples is that a key of `url` or `href` signifies it's a single object that is lazy loaded from the value specified. Any other keys assume that it's a nested set of URLs (like in the array situation, but accessible via the keys - e.g. object.attribute.something in the above example).
+
+It is required that the URL is a complete URL including a protocol starting with "http". To configure this use code like:
+
+```ruby
+class Person < Flexirest::Base
+  get :find, "/people/:id", :lazy => [:orders, :refunds]
+end
+```
+
+And use it like this:
+
+```ruby
+# Makes a call to /people/1
+@person = Person.find(1)
+
+# Makes a call to the first URL found in the "books":[...] array in the article response
+# only makes the HTTP request when first used though
+@person.books.first.name
+```
+
+## Type 3 - HAL Auto-loaded Resources
+
+You don't need to define lazy attributes if they are defined using [HAL](http://stateless.co/hal_specification.html) (with an optional embedded representation). If your resource has an `_links` item (and optionally an `_embedded` item) then it will automatically treat the linked resources (with the `_embedded` cache) as if they were defined using `:lazy` as per type 2 above.
+
+If you need to, you can access properties of the HAL association. By default just using the HAL association gets the embedded resource (or requests the remote resource if not available in the `_embedded` list).
+
+```ruby
+@person = Person.find(1)
+@person.students[0]._hal_attributes("title")
+```
+
+## Type 4 - Nested Resources
+
+It's common to have resources that are logically children of other resources. For example, suppose that your API includes these endpoints:
+
+| HTTP Verb | Path                        |                                          |
+|-----------|-----------------------------|------------------------------------------|
+| POST      | /magazines/:magazine_id/ads | create a new ad belonging to a magazine  |
+| GET       | /magazines/:magazine_id/ads | display a list of all ads for a magazine |
+
+In these cases, your child class will contain the following:
+
+```ruby
+class Ad < Flexirest::Base
+  post :create, "/magazines/:magazine_id/ads"
+  get :all, "/magazines/:magazine_id/ads"
+end
+```
+
+You can then access Ads by specifying their magazine IDs:
+
+```ruby
+Ad.all(magazine_id: 1)
+Ad.create(magazine_id: 1, title: "My Add Title")
+```
+
+## Type 5 - JSON API Auto-loaded Resources
+
+If attributes are defined using [JSON API](http://jsonapi.org), you don't need to define lazy attributes. If your resource has a `links` object with a `related` item, it will automatically treat the linked resources as if they were defined using `:lazy`.
+
+You need to activate JSON API by specifying the `json_api` proxy:
+
+```ruby
+class Article < Flexirest::Base
+  proxy :json_api
+end
+```
+
+If you want to embed linked resources directly in the response (i.e. request a JSON API compound document), use the `includes` class method. The linked resource is accessed in the same was as if it was lazily loaded, but without the extra request:
+
+```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
+```
+
+
+-----
+
+[< Faraday configuration](faraday-configuration.md) | [Combined example >](combined-example.md)

data/docs/authentication.md

@@ -0,0 +1,76 @@
+# *Flexirest:* Authentication
+
+## Basic authentication
+
+You can authenticate with Basic authentication by putting the username and password in to the `base_url` or by setting them within the specific model:
+
+```ruby
+class Person < Flexirest::Base
+  username 'api'
+  password 'eb693ec-8252c-d6301-02fd0-d0fb7-c3485'
+
+  # ...
+end
+```
+
+You can also pass in a Proc or a block to `username` and `password` if you want to dynamically pull it from somewhere, e.g. a [Current class descending from ActiveSupport::CurrentAttributes](http://edgeapi.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
+
+```ruby
+class Person < Flexirest::Base
+  username -> (obj) { obj ? Account.find(obj.id).username : Current.username }
+  password do
+    Rails.configuration.x.default_password
+  end
+
+  get :all, "/people"
+  get :find, "/people/:id"
+end
+```
+
+In the above example, the `username` call handles things differently if it's called from an object context:
+
+```ruby
+person = Person.new(id: 1234)
+person.find
+```
+
+Or if it's called from a class context:
+
+```ruby
+Person.find(id: 1234)
+```
+
+## Api-Auth
+
+Using the [Api-Auth](https://github.com/mgomes/api_auth) integration it is very easy to sign requests. Include the Api-Auth gem in your `Gemfile` and  then add it to your application. Then simply configure Api-Auth one time in your app and all requests will be signed from then on.
+
+```ruby
+require 'api-auth'
+
+@access_id = '123456'
+@secret_key = 'abcdef'
+Flexirest::Base.api_auth_credentials(@access_id, @secret_key)
+```
+
+You can also specify different credentials for different models just like configuring `base_url`:
+
+```ruby
+class Person < Flexirest::Base
+  api_auth_credentials '123456', 'abcdef'
+end
+```
+
+For more information on how to generate an access id and secret key please read the [Api-Auth](https://github.com/mgomes/api_auth) documentation.
+
+If you want to specify either the `:digest` or `:override_http_method` to ApiAuth, you can pass these in as options after the access ID and secret key, for example:
+
+```ruby
+class Person < Flexirest::Base
+  api_auth_credentials '123456', 'abcdef', digest: "sha256"
+end
+```
+
+
+-----
+
+[< Lazy loading](lazy-loading.md) | [Body types >](body-types.md)

data/docs/automatic-conversion-of-fields-to-datedatetime.md

@@ -0,0 +1,34 @@
+# *Flexirest:* Automatic conversion of fields to Date/DateTime
+
+By default Flexirest will attempt to convert all fields to a `Date` or `DateTime` object if it's a string and the value matches certain regular expressions. However, on large responses this can be computationally expensive. You can disable this automatic conversion completely with:
+
+```ruby
+Flexirest::Base.disable_automatic_date_parsing = true
+```
+
+Additionally, you can specify when mapping the methods which fields should be parsed (so you can disable it in general, then apply it to particular known fields):
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', parse_fields: [:created_at, :updated_at]
+end
+```
+
+It is also possible to whitelist fields that should be parsed in your models, which is useful if you are instantiating these objects directly. The specified fields also apply automatically to request mapping.
+
+```ruby
+class Person < Flexirest::Base
+  parse_date :updated_at, :created_at
+end
+
+# to disable all mapping
+class Disabled < Flexirest::Base
+  parse_date :none
+end
+```
+
+This system respects `disable_automatic_date_parsing`, and will default to mapping everything - unless a `parse_date` whitelist is specified, or automatic parsing is globally disabled.
+
+-----
+
+[< Per-request parameter encoding](per-request-parameter-encoding.md) | [Raw requests >](raw-requests.md)

data/docs/basic-usage.md

@@ -0,0 +1,103 @@
+# *Flexirest:* Basic usage
+
+First you need to create your new model class `app/models/person.rb`:
+
+```ruby
+class Person < Flexirest::Base
+  base_url "https://www.example.com/api/v1"
+
+  get :all, "/people"
+  get :find, "/people/:id"
+  put :save, "/people/:id"
+  post :create, "/people"
+  delete :remove, "/people/:id"
+end
+```
+
+Note I've specified the `base_url` in the class above. This is useful where you want to be explicit or use different APIs for some classes and be explicit. If you have one server that's generally used, you can set it once with a simple line in a `config/initializer/{something}.rb` file:
+
+```ruby
+Flexirest::Base.base_url = "https://www.example.com/api/v1"
+```
+
+Any `base_url` settings in specific classes override this declared default. You can also assign an array of URLs to `base_url` and Flexirest will randomly pull one of the URLs for each request, giving you a very simplistic load balancing (it doesn't know about the health or load levels of the backends).
+
+You can then use your new class like this:
+
+```ruby
+# Create a new person
+@person = Person.create(
+  first_name:"John"
+  last_name:"Smith"
+)
+
+# Find a person (not needed after creating)
+id = @person.id
+@person = Person.find(id)
+
+# Update a person
+@person.last_name = "Jones"
+@person.save
+
+# Get all people
+@people = Person.all
+@people.each do |person|
+  puts "Hi " + person.first_name
+end
+```
+
+For `delete` requests whether an API can handle a body or not is undefined. The default is to ignore any parameters not sent in the URL named parameters, but you can optionally specify `send_delete_body` and it will encode them in your chosen way into the body.
+
+```
+  delete :remove, "/people/:id", send_delete_body: true
+```
+
+If an API returns an array of results and you have [will_paginate](https://rubygems.org/gems/will_paginate) installed then you can call the paginate method to return a particular page of the results (note: this doesn't reduce the load on the server, but it can help with pagination if you have a cached response).
+
+```ruby
+@people = Person.all
+@people.paginate(page: 1, per_page: 10).each do |person|
+  puts "You made the first page: " + person.first_name
+end
+```
+
+Note, you can assign to any attribute, whether it exists or not before and read from any attribute (which will return nil if not found). If you pass a string or a number to a method it will assume that it's for the "id" field. Any other field values must be passed as a hash and you can't mix passing a string/number and a hash.
+
+```ruby
+@person = Person.find(1234)  # valid
+@person = Person.find("1234")  # valid
+@person = Person.find(:id => 1234)  # valid
+@person = Person.find(:id => 1234, :name => "Billy")  # valid
+@person = Person.find(1234, :name => "Billy")  # invalid
+```
+
+You can also call any mapped method as an instance variable which will pass the current attribute set in as parameters (either GET or POST depending on the mapped method type). If the method returns a single instance it will assign the attributes of the calling object and return itself. If the method returns a list of instances, it will only return the list. So, we could rewrite the create call above as:
+
+```ruby
+@person = Person.new
+@person.first_name = "John"
+@person.last_name  = "Smith"
+@person.create
+puts @person.id
+```
+
+The response of the #create call set the attributes at that point (any manually set attributes before that point are removed).
+
+If you have attributes beginning with a number, Ruby doesn't like this. So, you can use hash style notation to read/write the attributes:
+
+```ruby
+@tv = Tv.find(model:"UE55U8000") # { "properties" : {"3d" : false} }
+puts @tv.properties["3d"]
+@tv.properties["3d"] = true
+```
+
+If you want to debug the response, using inspect on the response object may well be useful. However, if you want a simpler output, then you can call `#to_json` on the response object:
+
+```ruby
+@person = Person.find(email:"something@example.com")
+puts @person.to_json
+```
+
+-----
+
+[< Introduction](../README.md) | [Ruby on Rails integration >](ruby-on-rails-integration.md)

data/docs/body-types.md

@@ -0,0 +1,33 @@
+# *Flexirest:* Body types
+
+By default Flexirest formats the request bodies as normal CGI parameters in `K=V&K2=V2` format. However, if you want to use JSON for your PUT/POST requests, you can use choose to configure Flexirest to do so (the other option, the default, is `:form_encoded`):
+
+```ruby
+class Person < Flexirest::Base
+  request_body_type :json
+  # ...
+end
+```
+
+or
+
+```ruby
+Flexirest::Base.request_body_type = :json
+```
+
+This will also set the header `Content-Type` to `application/x-www-form-urlencoded` by default or `application/json; charset=utf-8` when `:json`. You can override this using the callback `before_request`.
+
+If you have an API that is inconsistent in its body type requirements, you can also specify it on the individual method mapping:
+
+```ruby
+class Person < Flexirest::Base
+  request_body_type :form_encoded # This is the default, but just for demo purposes
+
+  get :all, '/people', request_body_type: :json
+end
+```
+
+
+-----
+
+[< Authentication](authentication.md) | [Parallel requests >](parallel-requests.md)

data/docs/caching.md

@@ -0,0 +1,26 @@
+# *Flexirest:* Caching
+
+Expires and ETag based caching is enabled by default, but with a simple line in the application.rb/production.rb you can disable it:
+
+```ruby
+Flexirest::Base.perform_caching = false
+```
+
+or you can disable it per classes with:
+
+```ruby
+class Person < Flexirest::Base
+  perform_caching false
+end
+```
+
+If Rails is defined, it will default to using Rails.cache as the cache store, if not, you'll need to configure one with a `ActiveSupport::Cache::Store` compatible object using:
+
+```ruby
+Flexirest::Base.cache_store = Redis::Store.new("redis://localhost:6379/0/cache")
+```
+
+
+-----
+
+[< Combined example](combined-example.md) | [Using callbacks >](using-callbacks.md)

data/docs/combined-example.md

@@ -0,0 +1,72 @@
+# *Flexirest:* Combined example
+
+OK, so let's say you have an API for getting articles. Each article has a property called `title` (which is a string) and a property `images` which includes a list of URIs. Following this URI would take you to a image API that returns the image's `filename` and `filesize`. We'll also assume this is a HAL compliant API. We would declare our two models (one for articles and one for images) like the following:
+
+```ruby
+class Article < Flexirest::Base
+  get :find, '/articles/:id', has_many:{:images => Image} # ,lazy:[:images] isn't needed as we're using HAL
+end
+
+class Image < Flexirest::Base
+  # You may have mappings here
+
+  def nice_size
+    "#{size/1024}KB"
+  end
+end
+```
+
+We assume the /articles/:id call returns something like the following:
+
+```json
+{
+  "title": "Fly Fishing",
+  "author": "J R Hartley",
+  "images": [
+    "http://api.example.com/images/1",
+    "http://api.example.com/images/2"
+  ]
+}
+```
+
+We said above that the /images/:id call would return something like:
+
+```json
+{
+  "filename": "http://cdn.example.com/images/foo.jpg",
+  "filesize": 123456
+}
+```
+
+When it comes time to use it, you would do something like this:
+
+```ruby
+@article = Article.find(1)
+@article.images.is_a?(Flexirest::LazyAssociationLoader)
+@article.images.size == 2
+@article.images.each do |image|
+  puts image.inspect
+end
+```
+
+At this point, only the HTTP call to '/articles/1' has been made. When you actually start using properties of the images list/image object then it makes a call to the URL given in the images list and you can use the properties as if it was a nested JSON object in the original response instead of just a URL:
+
+```ruby
+@image = @article.images.first
+puts @image.filename
+# => http://cdn.example.com/images/foo.jpg
+puts @image.filesize
+# => 123456
+```
+
+You can also treat `@image` looks like an Image class (and you should 100% treat it as one) it's technically a lazy loading proxy. So, if you cache the views for your application should only make HTTP API requests when actually necessary.
+
+```ruby
+puts @image.nice_size
+# => 121KB
+```
+
+
+-----
+
+[< Associations](associations.md) | [Caching >](caching.md)

data/docs/debugging.md

@@ -0,0 +1,32 @@
+# *Flexirest:* Debugging
+
+You can turn on verbose debugging to see what is sent to the API server and what is returned in one of these two ways:
+
+```ruby
+class Article < Flexirest::Base
+  verbose true
+end
+
+class Person < Flexirest::Base
+  verbose!
+end
+```
+
+By default verbose logging isn't enabled, so it's up to the developer to enable it (and remember to disable it afterwards). It does use debug level logging, so it shouldn't fill up a correctly configured production server anyway.
+
+If you prefer to record the output of an API call in a more automated fashion you can use a callback called `record_response` like this:
+
+```ruby
+class Article < Flexirest::Base
+  record_response do |url, response|
+    File.open(url.parameterize, "w") do |f|
+      f << response.body
+    end
+  end
+end
+```
+
+
+-----
+
+[< Filtering result lists](filtering-result-lists.md) | [XML responses >](xml-responses.md)

data/docs/default-parameters.md

@@ -0,0 +1,37 @@
+# *Flexirest:* Default parameters
+
+If you want to specify default parameters you shouldn't use a path like:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people?all=true' # THIS IS WRONG!!!
+end
+```
+
+You should use a defaults option to specify the defaults, then they will be correctly overwritten when making the request
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', :defaults => {:active => true}
+end
+
+@people = Person.all(active:false)
+```
+
+If you specify `defaults` as a `Proc` this will be executed with the set parameters (which you can change). For example to allow you to specify a reference (but the API wants it formated as "id-reference") you could use:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, "/", defaults: (Proc.new do |params|
+    reference = params.delete(:reference) # Delete the old parameter
+    {
+      id: "id-#{reference}"
+    } # The last thing is the hash of defaults
+  end)
+end
+```
+
+
+-----
+
+[< Translating APIs](translating-apis.md) | [Root elements >](root-elements.md)

data/docs/faking-calls.md

@@ -0,0 +1,22 @@
+# *Flexirest:* Faking calls
+
+There are times when an API hasn't been developed yet, so you want to fake the API call response. To do this, you can simply pass a `:fake` option when mapping the call containing the response.
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', fake: [{first_name:"Johnny"}, {first_name:"Bob"}]
+end
+```
+
+You may want to run a proc when faking data (to put information from the parameters in to the response or return different responses depending on the parameters). To do this just pass a proc to `:fake`:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, '/people', fake: ->(request) { {result: request.get_params[:id]} }
+end
+```
+
+
+-----
+
+[< Parallel requests](parallel-requests.md) | [Per-request timeouts >](per-request-timeouts.md)

data/docs/faraday-configuration.md

@@ -0,0 +1,28 @@
+# *Flexirest:* Faraday configuration
+
+Flexirest uses Faraday to allow switching HTTP backends, the default is to just use Faraday's default. To change the used backend just set it in the class by setting `adapter` to a Faraday supported adapter symbol.
+
+```ruby
+Flexirest::Base.adapter = :net_http
+# or ...
+Flexirest::Base.adapter = :patron
+```
+
+In versions before 1.2.0 the adapter was hardcoded to `:patron`, so if you want to ensure it still uses Patron, you should set this setting.
+
+If you want more control you can pass a **complete** configuration block ("complete" means that the block does not _override_ [the default configuration](https://github.com/flexirest/flexirest/blob/5b1953d89e26c02ca74f74464ccb7cd4c9439dcc/lib/flexirest/configuration.rb#L184-L201), but rather _replaces_ it).
+
+For available configuration variables look into the [Faraday documentation](https://github.com/lostisland/faraday).
+
+```ruby
+Flexirest::Base.faraday_config do |faraday|
+  faraday.adapter(:net_http)
+  faraday.options.timeout       = 10
+  faraday.headers['User-Agent'] = "Flexirest/#{Flexirest::VERSION}"
+end
+```
+
+
+-----
+
+[< Ruby on Rails integration](ruby-on-rails-integration.md) | [Associations >](associations.md)

data/docs/filtering-result-lists.md

@@ -0,0 +1,16 @@
+# *Flexirest:* Filtering result lists
+
+If the API returns a JSON list of items, this is retured to you as a `Flexirest::ResultIterator` object. A `ResultIterator` sorts simple filtering of the list using a `where` method based on values matching a specified criteria (or matching using regular expressions):
+
+```ruby
+class Article < Flexirest::Base
+  get :all, "/articles"
+end
+
+Article.all.where(published: true, department: /technical\-/)
+```
+
+
+-----
+
+[< Validation](validation.md) | [Debugging >](debugging.md)