Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 913773c086
Fetching contributors…

Cannot retrieve contributors at this time

file 96 lines (74 sloc) 2.649 kb

Sawyer

Sawyer is an experimental RESTful user agent built on top of Faraday.

Think of Faraday as the nerdy scientist behind a REST API. Sure, he knows the technical details of how to communicate with an application. But he also gets overly obsessive about alternate timelines to be of much use.

Sawyer knows what needs to be done. He gets in there, assesses the situation, and figures out the next action.

What the What?

The main idea is that each resource has a JSON Schema file detailing the available properties and relations. The relations describe the schema, HTTP method, and href. However, a relation is not accessible on a resource unless the resource also mentions that relation. For instance, a schema of a user may describe these relations:

{ "relations":
  [ {"rel": "self"}
  , {"rel": "update", "method": "patch"}
  , {"rel": "destroy", "method": "delete"}
  , {"rel": "favorites"}
  , {"rel": "favorites:create", "method": "post"}
  ]
}

Now, when you get a User, you may see these relations:

{ "_links":
  [ {"rel": "self", "href": "/users/1"}
  , {"rel": "update"}
  , {"rel": "favorites", "href": "/users/1/friends"}
  , {"rel": "favorites:create"}
  ]
}

The Sawyer agent should know that the 'destroy' relation is inaccessible for some reason in the application.

(Possible) Usage

# SushiHub is a an example REST API -- A social network for Sushi
# Enthusiasts

# setup the auth info and the API endpoint so we can grab the schema 
# info and initial actions.
agent = Sawyer::Agent.new
agent.load 'https://api.sushihub.com'

# salmon is all you need
# mime: application/vnd.sushihub+json
# /nigiri/1
sake = agent.nigiri.get 'sake'

# mime: application/vnd.sushihub+json
# /users/technoweenie
user = agent.user.get 'technoweenie'

# user has "favorites:create" rel with method=POST
user.favorites.create sake

Implemented

This library is experimental. Don't expect there to be tests, or for anything to work. APIs will change. Sawyer may even be a complete failure. Whatever happened, happened.

# tested on ruby 1.9.2 with these gems: sinatra, faraday, yajl-ruby
# bundler coming soon, lol
# run example/sushihub.rb to start the example app
#
# start a sawyer console with: `irb -r ./lib/sawyer`
require 'pp'
agent = Sawyer::Agent.new
agent.load 'http://localhost:4567'

pp agent.profiles.keys
pp agent.profiles['/schema/user'].properties
Something went wrong with that request. Please try again.