Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 98 lines (74 sloc) 2.649 kb
a6ee3c4 @technoweenie initial readme
technoweenie authored
1 # Sawyer
2
3 Sawyer is an experimental RESTful user agent built on top of
4 [Faraday][faraday].
5
6 ![](http://www.lost-isle.net/images/s5/09x01.jpg)
7
8 Think of Faraday as the nerdy scientist behind a REST API. Sure, he
9 knows the technical details of how to communicate with an application.
10 But he also gets overly obsessive about alternate timelines to be of
11 much use.
12
13 ![](http://cdn.tvovermind.com/wp-content/uploads/2009/03/lafleur-296x3001.jpg)
14
15 Sawyer knows what needs to be done. He gets in there, assesses the
16 situation, and figures out the next action.
808837e @technoweenie document relations
technoweenie authored
17
18 ## What the What?
19
20 The main idea is that each resource has a JSON Schema file detailing the
21 available properties and relations. The relations describe the schema,
22 HTTP method, and href. However, a relation is not accessible on a
23 resource unless the resource also mentions that relation. For instance,
24 a schema of a user may describe these relations:
25
26 ``` javascript
27 { "relations":
28 [ {"rel": "self"}
29 , {"rel": "update", "method": "patch"}
30 , {"rel": "destroy", "method": "delete"}
913773c @technoweenie go with the sushihub example
technoweenie authored
31 , {"rel": "favorites"}
32 , {"rel": "favorites:create", "method": "post"}
808837e @technoweenie document relations
technoweenie authored
33 ]
34 }
35 ```
36
37 Now, when you get a User, you may see these relations:
38
39 ``` javascript
40 { "_links":
41 [ {"rel": "self", "href": "/users/1"}
42 , {"rel": "update"}
913773c @technoweenie go with the sushihub example
technoweenie authored
43 , {"rel": "favorites", "href": "/users/1/friends"}
44 , {"rel": "favorites:create"}
808837e @technoweenie document relations
technoweenie authored
45 ]
46 }
47 ```
48
49 The Sawyer agent should know that the 'destroy' relation is inaccessible
50 for some reason in the application.
a6ee3c4 @technoweenie initial readme
technoweenie authored
51
52 ## (Possible) Usage
53
54 ``` ruby
55 # SushiHub is a an example REST API -- A social network for Sushi
56 # Enthusiasts
57
58 # setup the auth info and the API endpoint so we can grab the schema
59 # info and initial actions.
b36b771 @technoweenie initial implementation: we can hit the api endpoint and get the schem…
technoweenie authored
60 agent = Sawyer::Agent.new
a6ee3c4 @technoweenie initial readme
technoweenie authored
61 agent.load 'https://api.sushihub.com'
62
63 # salmon is all you need
913773c @technoweenie go with the sushihub example
technoweenie authored
64 # mime: application/vnd.sushihub+json
a6ee3c4 @technoweenie initial readme
technoweenie authored
65 # /nigiri/1
66 sake = agent.nigiri.get 'sake'
67
913773c @technoweenie go with the sushihub example
technoweenie authored
68 # mime: application/vnd.sushihub+json
a6ee3c4 @technoweenie initial readme
technoweenie authored
69 # /users/technoweenie
70 user = agent.user.get 'technoweenie'
b36b771 @technoweenie initial implementation: we can hit the api endpoint and get the schem…
technoweenie authored
71
72 # user has "favorites:create" rel with method=POST
a6ee3c4 @technoweenie initial readme
technoweenie authored
73 user.favorites.create sake
74 ```
75
b36b771 @technoweenie initial implementation: we can hit the api endpoint and get the schem…
technoweenie authored
76 ## Implemented
77
78 This library is experimental. Don't expect there to be tests, or for
79 anything to work. APIs will change. Sawyer may even be a complete
d9dc971 @technoweenie can't help it
technoweenie authored
80 failure. Whatever happened, happened.
b36b771 @technoweenie initial implementation: we can hit the api endpoint and get the schem…
technoweenie authored
81
82 ```ruby
83 # tested on ruby 1.9.2 with these gems: sinatra, faraday, yajl-ruby
84 # bundler coming soon, lol
85 # run example/sushihub.rb to start the example app
86 #
87 # start a sawyer console with: `irb -r ./lib/sawyer`
88 require 'pp'
89 agent = Sawyer::Agent.new
90 agent.load 'http://localhost:4567'
91
92 pp agent.profiles.keys
93 pp agent.profiles['/schema/user'].properties
94 ```
95
529d00d @technoweenie link to faraday
technoweenie authored
96 [faraday]: https://github.com/technoweenie/faraday
b36b771 @technoweenie initial implementation: we can hit the api endpoint and get the schem…
technoweenie authored
97
Something went wrong with that request. Please try again.