sawyer 0.0.1

data/example/user.schema.json

@@ -0,0 +1,51 @@
+{
+  "type": "object",
+  "relations": [
+    {"rel": "all", "href": "/users"},
+    {"rel": "create", "href": "/users", "method": "post"},
+    {"rel": "favorites", "schema": "/schema/nigiri"},
+    {"rel": "favorites/create", "method": "post"}
+  ],
+  "properties": {
+    "id": {
+      "type": "integer",
+      "minimum": 1,
+      "readonly": true
+    },
+    "login": {
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string",
+      "pattern": "\\d{8}T\\d{6}Z",
+      "readonly": true
+    },
+    "_links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "rel": {
+            "type": "string"
+          },
+          "href": {
+            "type": "string",
+            "optional": true
+          },
+          "method": {
+            "type": "string",
+            "default": "get"
+          },
+          "schema": {
+            "type": "string",
+            "optional": true
+          }
+        },
+        "additionalProperties": false
+      },
+      "additionalProperties": false,
+      "readonly": true
+    }
+  }
+}
+

data/lib/sawyer.rb

@@ -0,0 +1,14 @@
+module Sawyer
+  VERSION = "0.0.1"
+
+  class Error < StandardError; end
+end
+
+require 'set'
+
+%w(
+  resource
+  relation
+  response
+  agent
+).each { |f| require File.expand_path("../sawyer/#{f}", __FILE__) }

data/lib/sawyer/agent.rb

@@ -0,0 +1,82 @@
+require 'faraday'
+require 'uri_template'
+
+module Sawyer
+  class Agent
+    NO_BODY = Set.new [:get, :head]
+
+    # Agents handle making the requests, and passing responses to
+    # Sawyer::Response.
+    #
+    # endpoint - String URI of the API entry point.
+    def initialize(endpoint)
+      @endpoint = endpoint
+      @conn     = Faraday.new endpoint
+      yield @conn if block_given?
+    end
+
+    # Public: Hits the root of the API to get the initial actions.
+    #
+    # Returns a Sawyer::Response.
+    def start
+      call :get, @endpoint
+    end
+
+    # Makes a request through Faraday.
+    #
+    # method  - The Symbol name of an HTTP method.
+    # url     - The String URL to access.  This can be relative to the Agent's
+    #           endpoint.
+    # data    - The Optional Hash or Resource body to be sent.  :get or :head
+    #           requests can have no body, so this can be the options Hash
+    #           instead.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #
+    # Returns a Sawyer::Response.
+    def call(method, url, data = nil, options = nil)
+      if NO_BODY.include?(method)
+        options ||= data
+        data      = nil
+      end
+
+      options ||= {}
+      url = URITemplate.new(url).expand(options[:uri] || {})
+      res = @conn.send method, url do |req|
+        req.body = encode_body(data) if data 
+        if params = options[:query]
+          req.params.update params
+        end
+        if headers = options[:headers]
+          req.headers.update headers
+        end
+      end
+
+      Response.new self, res
+    end
+
+    # Encodes an object to a string for the API request.
+    #
+    # data - The Hash or Resource that is being sent.
+    #
+    # Returns a String.
+    def encode_body(data)
+      Yajl.dump data
+    end
+
+    # Decodes a String response body to a resource.
+    #
+    # str - The String body from the response.
+    #
+    # Returns an Object resource (Hash by default).
+    def decode_body(str)
+      Yajl.load str, :symbolize_keys => true
+    end
+
+    def inspect
+      %(<#{self.class} #{@endpoint}>)
+    end
+  end
+end
+

data/lib/sawyer/relation.rb

@@ -0,0 +1,253 @@
+module Sawyer
+  class Relation
+    class Map
+      # Tracks the available next actions for a resource, and
+      # issues requests for them.
+      def initialize
+        @map = {}
+      end
+
+      # Adds a Relation to the map.
+      #
+      # rel - A Relation.
+      #
+      # Returns nothing.
+      def <<(rel)
+        @map[rel.name] = rel
+      end
+
+      # Gets the raw Relation by its name.
+      #
+      # key - The Symbol name of the Relation.
+      #
+      # Returns a Relation.
+      def [](key)
+        @map[key.to_sym]
+      end
+
+      # Gets the number of mapped Relations.
+      #
+      # Returns an Integer.
+      def size
+        @map.size
+      end
+
+      # Gets a list of the Relation names.
+      #
+      # Returns an Array of Symbols in no specific order.
+      def keys
+        @map.keys
+      end
+
+      def inspect
+        %(#<#{self.class}: #{@map.keys.inspect}>)
+      end
+    end
+
+    attr_reader :agent,
+      :name,
+      :href,
+      :method,
+      :available_methods
+
+    # Public: Builds an index of Relations from the value of a `_links`
+    # property in a resource.  :get is the default method.  Any links with
+    # multiple specified methods will get multiple relations created.
+    #
+    # index - The Hash mapping Relation names to the Hash Relation
+    #         options.
+    # rels  - A Relation::Map to store the Relations.
+    #
+    # Returns a Relation::Map
+    def self.from_links(agent, index, rels = Map.new)
+      if index.is_a?(Array)
+        raise ArgumentError, "Links must be a hash of rel => {_href => '...'}: #{index.inspect}"
+      end
+
+      index.each do |name, options|
+        rels << from_link(agent, name, options)
+      end if index
+
+      rels
+    end
+
+    # Public: Builds a single Relation from the given options.  These are
+    # usually taken from a `_links` property in a resource.
+    #
+    # agent   - The Sawyer::Agent that made the request.
+    # name    - The Symbol name of the Relation.
+    # options - A Hash containing the other Relation properties.
+    #           :href   - The String URL of the next action's location.
+    #           :method - The optional String HTTP method.
+    #
+    # Returns a Relation.
+    def self.from_link(agent, name, options)
+      new agent, name, options[:href], options[:method]
+    end
+
+    # A Relation represents an available next action for a resource.
+    #
+    # agent  - The Sawyer::Agent that made the request.
+    # name   - The Symbol name of the relation.
+    # href   - The String URL of the location of the next action.
+    # method - The Symbol HTTP method.  Default: :get
+    def initialize(agent, name, href, method = nil)
+      @agent = agent
+      @name  = name.to_sym
+      @href  = href.to_s
+
+      methods = nil
+
+      if method.is_a? String
+        if method.size.zero?
+          method = nil
+        else
+          method.downcase!
+          methods = method.split(',').map! do |m|
+            m.strip!
+            m.to_sym
+          end
+          method = methods.first
+        end
+      end
+
+      @method = (method || :get).to_sym
+      @available_methods = Set.new methods || [@method]
+    end
+
+    # Public: Makes an API request with the curent Relation using HEAD.
+    #
+    # data    - The Optional Hash or Resource body to be sent.  :get or :head
+    #           requests can have no body, so this can be the options Hash
+    #           instead.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def head(options = nil)
+      options ||= {}
+      options[:method] = :head
+      call options
+    end
+
+    # Public: Makes an API request with the curent Relation using GET.
+    #
+    # data    - The Optional Hash or Resource body to be sent.  :get or :head
+    #           requests can have no body, so this can be the options Hash
+    #           instead.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def get(options = nil)
+      options ||= {}
+      options[:method] = :get
+      call options
+    end
+
+    # Public: Makes an API request with the curent Relation using POST.
+    #
+    # data    - The Optional Hash or Resource body to be sent.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def post(data = nil, options = nil)
+      options ||= {}
+      options[:method] = :post
+      call data, options
+    end
+
+    # Public: Makes an API request with the curent Relation using PUT.
+    #
+    # data    - The Optional Hash or Resource body to be sent.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def put(data = nil, options = nil)
+      options ||= {}
+      options[:method] = :put
+      call data, options
+    end
+
+    # Public: Makes an API request with the curent Relation using PATCH.
+    #
+    # data    - The Optional Hash or Resource body to be sent.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def patch(data = nil, options = nil)
+      options ||= {}
+      options[:method] = :patch
+      call data, options
+    end
+
+    # Public: Makes an API request with the curent Relation using DELETE.
+    #
+    # data    - The Optional Hash or Resource body to be sent.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def delete(data = nil, options = nil)
+      options ||= {}
+      options[:method] = :delete
+      call data, options
+    end
+
+    # Public: Makes an API request with the curent Relation using OPTIONS.
+    #
+    # data    - The Optional Hash or Resource body to be sent.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Returns a Sawyer::Response.
+    def options(data = nil, opt = nil)
+      opt ||= {}
+      opt[:method] = :options
+      call data, opt
+    end
+
+    # Public: Makes an API request with the curent Relation.
+    #
+    # data    - The Optional Hash or Resource body to be sent.  :get or :head
+    #           requests can have no body, so this can be the options Hash
+    #           instead.
+    # options - Hash of option to configure the API request.
+    #           :headers - Hash of API headers to set.
+    #           :query   - Hash of URL query params to set.
+    #           :method  - Symbol HTTP method.
+    #
+    # Raises ArgumentError if the :method value is not in @available_methods.
+    # Returns a Sawyer::Response.
+    def call(data = nil, options = nil)
+      m = options && options[:method]
+      if m && !@available_methods.include?(m == :head ? :get : m)
+        raise ArgumentError, "method #{m.inspect} is not available: #{@available_methods.to_a.inspect}"
+      end
+
+      @agent.call m || @method, @href, data, options
+    end
+
+    def inspect
+      %(#<#{self.class}: #{@name}: #{@method} #{@href}>)
+    end
+  end
+end
+

data/lib/sawyer/resource.rb

@@ -0,0 +1,69 @@
+module Sawyer
+  class Resource
+    SPECIAL_METHODS = Set.new %w(agent rels fields)
+    attr_reader :_agent, :_rels, :_fields
+
+    # Initializes a Resource with the given data.
+    #
+    # agent - The Sawyer::Agent that made the API request.
+    # data  - Hash of key/value properties.
+    def initialize(agent, data)
+      @_agent  = agent
+      @_rels   = Relation.from_links(agent, data.delete(:_links))
+      @_fields = Set.new []
+      data.each do |key, value|
+        @_fields << key
+        instance_variable_set "@#{key}", process_value(value)
+      end
+    end
+
+    # Processes an individual value of this resource.  Hashes get exploded
+    # into another Resource, and Arrays get their values processed too.
+    #
+    # value - An Object value of a Resource's data.
+    #
+    # Returns an Object to set as the value of a Resource key.
+    def process_value(value)
+      case value
+      when Hash  then self.class.new(@_agent, value)
+      when Array then value.map { |v| process_value(v) }
+      else value
+      end
+    end
+
+    # Checks to see if the given key is in this resource.
+    #
+    # key - A Symbol key.
+    #
+    # Returns true if the key exists, or false.
+    def key?(key)
+      @_fields.include? key
+    end
+
+    ATTR_SETTER    = '='.freeze
+    ATTR_PREDICATE = '?'.freeze
+
+    # Provides access to a resource's attributes.
+    def method_missing(method, *args)
+      attr_name, suffix = method.to_s.scan(/([a-z0-9\_]+)(\?|\=)?$/i).first
+      if suffix == ATTR_SETTER
+        (class << self; self; end).send :attr_accessor, attr_name
+        @_fields << attr_name.to_sym
+        instance_variable_set "@#{attr_name}", args.first
+      elsif @_fields.include?(attr_name.to_sym)
+        value = instance_variable_get("@#{attr_name}")
+        case suffix
+        when nil
+          (class << self; self; end).send :attr_accessor, attr_name
+          value
+        when ATTR_PREDICATE then !!value
+        end
+      elsif suffix.nil? && SPECIAL_METHODS.include?(attr_name)
+        instance_variable_get "@_#{attr_name}"
+      else
+        super
+      end
+    end
+  end
+end
+