frenetic 0.0.12 → 0.0.20.alpha.0

data/.gitignore

@@ -16,3 +16,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+vendor

data/.irbrc

@@ -0,0 +1,3 @@
+require 'bundler'
+Bundler.require
+require 'awesome_print'

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p374

data/.travis.yml

@@ -1,4 +1,3 @@
 rvm:
-  - 1.9.2
   - 1.9.3
 script: bundle exec rspec --require spec_helper --order rand --color --format documentation

data/Gemfile

@@ -1,7 +1,5 @@
 source 'https://rubygems.org'
+ruby '1.9.3'
 
 # Specify your gem's dependencies in frenetic.gemspec
 gemspec
-
-gem 'awesome_print'
-gem 'fakefs',         '~> 0.4.0', require: false

data/README.md

@@ -9,7 +9,6 @@ An opinionated Ruby-based Hypermedia API (HAL+JSON) client.
 
 
 
-
 ## About
 
 fre&bull;net&bull;ic |frəˈnetik|<br/>
@@ -29,6 +28,7 @@ If you have not implemented a HAL+JSON API, then this will not work very well fo
 
 
 
+
 ## Opinions
 
 Like I said, it is opinionated. It is so opinionated, it is probably the biggest
@@ -37,7 +37,6 @@ a-hole you've ever met.
 Maybe in time, if you teach it, it will become more open-minded.
 
 
-
 ### HAL+JSON Content Type
 
 Frenetic expects all responses to be in [HAL+JSON][hal_json]. It chose that
@@ -45,45 +44,43 @@ standard because it is trying to make JSON API's respond in a predictable
 manner, which it thinks is an awesome idea.
 
 
-
-### Authentication
-
-Frenetic is going to try and use Basic Auth whether you like it or not. If
-that is not required, nothing will probably happen. But its going to send the
-header anyway.
-
-
-
 ### API Description
 
 The API's root URL must respond with a description, much like the
-[Spire.io][spire.io] API. This is crucial in order for Frenetic to work. If
-Frenetic doesn't know what the API contains, it can't parse any resource
-responses.
+[Spire.io][spire.io] API.
 
-It is expected that any subclasses of `Frenetic::Resource` will adhere to the
-schema defined here.
+This is crucial in order for Frenetic to work. If Frenetic doesn't know what
+the API contains, it can't navigate around it or parse any of it's responses.
 
-Example:
+**Example:**
 
 ```js
+// GET http://example.com/api
 {
-  "_links":{
-    "self":{"href":"/api/"},
-    "orders":{"href":"/api/orders"},
+  "_links": {
+    "self": {
+      "href": "/api/"
+    },
+    "orders": {
+      "href":"/api/orders"
+    },
+    "order": {
+      "href": "/api/orders/{id}",
+      "templated": true
+    }
   },
-  "_embedded":{
-    "schema":{
-      "_links":{
-        "self":{"href":"/api/schema"}
+  "_embedded": {
+    "schema": {
+      "_links": {
+        "self": { "href":"/api/schema" }
       },
-      "order":{
-        "description":"A widget order",
-        "type":"object",
-        "properties":{
-          "id":{"type":"integer"},
-          "first_name":{"type":"string"},
-          "last_name":{"type":"string"},
+      "order": {
+        "description": "A widget order",
+        "type": "object",
+        "properties": {
+          "id": { "type":"integer" },
+          "first_name": { "type":"string" },
+          "last_name": { "type":"string" },
         }
       }
     }
@@ -92,114 +89,144 @@ Example:
 ```
 
 This response will be requested by Frenetic whenever a call to
-`YourAPI.description` is made. The response is memoized so any future calls
-will not trigger another API request.
+`YourAPI.description` is made.
 
+**Note:** It is highly advised that you implement some sort of caching in both
+your API server as well as your API client. Refer to the [Caching][caching] section for
+more information.
 
 
 
-## Installation
 
-Add this line to your application's Gemfile:
 
-    gem 'frenetic'
+## Configuring
 
-And then execute:
+### Client Initialization
 
-    $ bundle
+Initializing an API client is really easy:
 
-Or install it yourself as:
+```ruby
+class MyApiClient
+  # Arbitrary example
+  def self.api
+    @api ||= Frenetic.new( url:'http://example.com/api' )
+  end
+end
+```
 
-    $ gem install frenetic
+At the bare minimum, Frenetic only needs to know what the URL of your API is.
 
 
+### Configuring
 
+Configuring Frenetic can be done during instantiation:
 
-## Usage
+```ruby
+Frenetic.new( url:'http://example.com', api_token:'123bada55k3y' )
+```
 
+Or with a block:
 
+```ruby
+f = Frenetic.new
+f.configure do |cfg|
+  cfg.url = 'http://example.com'
+  cfg.api_token = '123bada55key'
+end
+```
 
-### Client Initialization
+Or both...
 
 ```ruby
-MyAPI = Frenetic.new(
-  # 'adapter'    => :patron # Or some other Faraday-compatible Adapter. Defaults to `:net_http`
-  'url'          => 'https://api.yoursite.com',
-  'username'     => 'yourname',
-  'password'     => 'yourpassword',
-  'headers' => {
-    'accept' => 'application/vnd.yoursite-v1.hal+json'
-    # Optional
-    'user-agent' => 'Your Site's API Client', # Optional custom User Agent, just 'cuz
-  }
-)
+f = Frenetic.new( url:'http://example.com' )
+f.configure do |cfg|
+  cfg.api_token = '123bada55key'
+end
 ```
 
-Symbol- or string-based keys work equally well.
+#### Authentication
+
+Frenetic supports both Basic Auth and Tokens Auth via the appropriate Faraday
+middleware.
+
+##### Basic Auth
+
+To use Basic Auth, simply configure Frenetic with a `username` and `password`:
 
-#### Sending API Keys
+```ruby
+Frenetic.new( url:url, username:'user', password:'password' )
+```
 
-If the API you are consuming requires an API Key, you can provide that in the
-config hash:
+If your API uses an App ID and API Key pair, you can pass those as well:
 
 ```ruby
-Frenetic.new( url:'https://example.org', api_key:'abcde12345' )
+Frenetic.new( url:url, app_id:'123abcSHA1', api_key:'bada55SHA1k3y' )
 ```
 
-The value will be sent as the `:username` portion of the HTTP
-Basic Authentication header.
+The `app_id` and `api_key` values are simply aliases to `username` and
+`password`
 
-#### Sending API Keys with an App ID
+##### Token Auth
 
-If the API requires both an App ID or access token in addition to an API Key,
-you can provide that in the config hash as well:
+To use Token Auth, simply configure Frenetic with your token:
 
 ```ruby
-Frenetic.new( url:'https://example.org', app_id:'abcde12345', api_key:'mysecret' )
+Frenetic.new( url:url, api_token:'bada55SHA1t0k3n' )
 ```
 
-The App ID will be sent as the `:username` and the API Key will be sent as the
-password portion of the HTTP Basic Authentication header.
 
+#### Response Caching
 
+If configured to do so, Frenetic will autotmatically cache API responses.
 
-### Response Caching
+*It is highly recommended that you turn this feature on!*
 
-If configured to do so, Frenetic will autotmatically cache appropriate responses
-through [Rack::Cache][rack_cache]. Only on-disk stores are supported right now.
+##### Rack::Cache
 
-Add the following `Rack::Cache` configuration options when initializing Frenetic:
+```ruby
+Frenetic.new( url:url, cache: :rack )
+```
+
+Passing in a cache option of `:rack` will cause Frenetic to use Faraday's
+`Rack::Cache` middleware with a set of sane default configuration options.
+
+If you wish to provide your own configuration options:
 
 ```ruby
-MyAPI = Frenetic.new(
-  ...
-  'cache' => {
-    'metastore'   => 'file:/path/to/where/you/want/to/store/files/meta',
-    'entitystore' => 'file:/path/to/where/you/want/to/store/files/meta'
-  }
-)
+Frenetic.new({
+  url: url,
+  cache: {
+    metastore:     'file:tmp/rack/meta',
+    entitystore:   'file:tmp/rack/body',
+    ignore_headers: %w{Authorization Set-Cookie X-Content-Digest}
+  }})
 ```
 
-The `cache` options are passed directly to `Rack::Cache`, so anything it
-supports can be added to the Hash.
+Any key/value pair contained in the `cache` hash will be passed directly onto
+the Rack::Cache middleware.
 
+##### Memcached
 
+**TODO**
 
-# Middleware
 
-Frenetic supports anything that Faraday does. You may specify additional
-middleware with the `use` method:
+#### Faraday Middleware
+
+Frenetic will yield its internal Faraday connection during initialization:
 
 ```ruby
-Frenetic.new( url:'http://example.org' ) do |config|
-  config.use :instrumentation
-  config.use MyMiddleware, { foo:123 }
+Frenetic.new( url:url ) do |builder|
+  # `builder` is the Faraday Connection instance with which you can
+  # add additional Faraday Middlewares or tweak the configuration.
 end
 ```
 
+You can then use the `builder` object as you see fit.
+
+
 
 
-### Making Requests
+## Usage
 
 Once you have created a client instance, you are free to use it however you'd
 like.
@@ -207,12 +234,20 @@ like.
 A Frenetic instance supports any HTTP verb that [Faraday][faraday] has
 impletented. This includes GET, POST, PUT, PATCH, and DELETE.
 
+```ruby
+api = Frenetic.new( url:url )
+
+api.get '/my_things/1'
+# { 'id' => 1, 'name' => 'My Thing', '_links' => { 'self' { 'href' => '/api/my_things/1' } } }
+```
 
+### Frenetic::Resource
 
-#### Frenetic::Resource
+An easier way to make requests for a resource is to create an object that
+inherits from `Frenetic::Resource`.
 
-An easier way to make requests for a resource is to have your model inherit from
-`Frenetic::Resource`. This makes it a bit easier to encapsulate all of your
+Not only does `Frenetic::Resource` handle the parsing of the raw API response
+into a Ruby object, but it also makes it a bit easier to encapsulate all of your
 resource's API requests into one place.
 
 ```ruby
@@ -220,14 +255,9 @@ class Order < Frenetic::Resource
 
   api_client { MyAPI }
 
-  class << self
-    def find( id )
-      if response = api.get( api.description.links.order.href.gsub('{id}', id.to_s) ) and response.success?
-        self.new( response.body )
-      else
-        raise OrderNotFound, "No Order found for #{id}"
-      end
-    end
+  # TODO: Write a better example for this.
+  def self.find_all_by_name( name )
+    api.get( search_url(name) ) and response.success?
   end
 end
 ```
@@ -244,35 +274,14 @@ class Order < Frenetic::Resource
 end
 ```
 
-When your model is initialized, it will contain attribute readers for every
-property defined in your API's schema or description. In theory, this allows an
-API to add, remove, or change properties without the need to directly update
-your model.
-
+When your model is initialized, it will contain getter methods for every
+property defined in your API's schema/description.
 
+Each time a request is made for a resource, Frenetic checks the API to see if
+the schema has changed. If so, it will redefine the the getter methods available
+on your Class. This is what Hypermedia APIs are all about, a loose coupling
+between client and server.
 
-### Interpretting Responses
-
-Any response body returned by a Frenetic generated API call will be returned as
-an OpenStruct-like object. This object responds to dot-notation as well as Hash
-keys and is enumerable.
-
-```ruby
-response.body.resources.orders.first
-```
-
-or
-
-```ruby
-response.body['_embedded']['orders'][0]
-```
-
-For your convenience, certain HAL+JSON keys have been aliased by methods to
-make your code a bit more readable:
-
-  * `_embedded` can be referenced as `resources`
-  * `_links` can be referenced as `links`
-  * `href` can be referenced as `url`
 
 
 
@@ -285,8 +294,12 @@ make your code a bit more readable:
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
+I would love to hear how other people are using this (if at all) and am open to
+ideas on how to support other Hypermedia formats like [Collection+JSON][coll_json].
+
 [hal_json]: http://stateless.co/hal_specification.html
 [spire.io]: http://api.spire.io/
-[roar]: https://github.com/apotonick/roar
+[caching]: #response-caching
 [faraday]: https://github.com/technoweenie/faraday
 [rack_cache]: https://github.com/rtomayko/rack-cache
+[coll_json]: http://amundsen.com/media-types/collection/

data/frenetic.gemspec

@@ -15,14 +15,13 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Frenetic::VERSION
 
-  gem.add_dependency             'faraday',             '~> 0.8.1'
+  gem.add_dependency             'faraday',             '~> 0.8.7'
   gem.add_dependency             'faraday_middleware',  '~> 0.9.0'
-  gem.add_dependency             'activesupport',       '>= 2'
-  gem.add_dependency             'rack-cache',          '~> 1.1'
-  gem.add_dependency             'addressable',         '~> 2.2'
+  gem.add_dependency             'activesupport',       '>= 3'
+  gem.add_dependency             'addressable',         '~> 2.3.4'
 
-  gem.add_development_dependency 'patron',              '~> 0.4.18'
+  gem.add_development_dependency 'awesome_print'
   gem.add_development_dependency 'rspec',               '~> 2.13.0'
+  gem.add_development_dependency 'rack-cache',          '~> 1.2'
   gem.add_development_dependency 'webmock',             '~> 1.11.0'
-  gem.add_development_dependency 'vcr',                 '~> 2.4.0'
 end

data/lib/frenetic.rb

@@ -1,66 +1,54 @@
-require 'addressable/uri'
+require 'socket'
 require 'faraday'
 require 'faraday_middleware'
-require 'rack-cache'
 
-require "frenetic/configuration"
-require "frenetic/hal_json"
-require "frenetic/resource"
-require "frenetic/version"
+require 'frenetic/concerns/configurable'
+require 'frenetic/middleware/hal_json'
+require 'frenetic/resource'
+require 'frenetic/resource_collection'
+require 'frenetic/version'
 
 class Frenetic
-  Error                 = Class.new(StandardError)
-  ConfigurationError    = Class.new(Error)
-  MissingAPIReference   = Class.new(Error)
-  InvalidAPIDescription = Class.new(Error)
-
   extend Forwardable
-  def_delegators :@connection, :get, :put, :post, :delete
-
-  attr_reader  :connection
-  alias_method :conn, :connection
+  include Configurable
 
-  def initialize( config = {} )
-    config      = Configuration.new( config )
+  def_delegators :connection, :get, :put, :post, :delete
 
-    yield config if block_given?
+  Error           = Class.new(StandardError)
+  ConfigError     = Class.new(Error)
+  ClientError     = Class.new(Error)
+  ServerError     = Class.new(Error)
+  ParsingError    = Class.new(Error)
+  HypermediaError = Class.new(Error)
 
-    api_url     = Addressable::URI.parse( config.url )
-    @root_url   = api_url.path
+  def connection
+    @connection ||= begin
+      validate_configuration!
 
-    @connection = Faraday.new( config.to_hash ) do |builder|
-      builder.use HalJson
+      Faraday.new( config ) do |builder|
+        configure_authentication builder
 
-      config.middleware.each { |mw| builder.use(*mw) }
+        builder.response :hal_json
 
-      builder.request :basic_auth, config.username, config.password
+        configure_caching builder
 
-      builder.response :logger if config.response[:use_logger]
+        @builder_config.call( builder ) if @builder_config
 
-      if config.cache.present?
-        builder.use FaradayMiddleware::RackCompatible, Rack::Cache::Context, config.cache
+        builder.adapter config.adapter
       end
-
-      builder.adapter config.adapter || :net_http
     end
   end
 
+  # It is highly advised that the server responds with some cache headers and
+  # the API Client is configured to use a Faraday caching strategy
   def description
-    @description ||= load_description
+    if response = get( config.url.to_s ) and response.success?
+      response.body
+    end
   end
 
-  # A naive approach to reloading a Frenetic instance for testing purpose.
-  def reload!
-    instance_variables.each { |var| instance_variable_set(var, nil) }
+  def schema
+    description['_embedded']['schema']
   end
 
-private
-
-  def load_description
-    if response = get( @root_url ) and response.success?
-      response.body
-    else
-      raise InvalidAPIDescription, "Status code #{response.status} encountered."
-    end
-  end
-end
+end