hateoas 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/.gitignore +6 -0
- data/Gemfile +4 -0
- data/README.md +120 -0
- data/Rakefile +1 -0
- data/SPEC.md +146 -0
- data/hateoas.gemspec +22 -0
- data/lib/hateoas.rb +43 -0
- data/lib/hateoas/version.rb +3 -0
- metadata +100 -0
data/.gitignore
ADDED
data/Gemfile
ADDED
data/README.md
ADDED
@@ -0,0 +1,120 @@
|
|
1
|
+
|
2
|
+
About
|
3
|
+
=====
|
4
|
+
|
5
|
+
HATEOAS helps you build hypermedia API clients, by providing a simple
|
6
|
+
interface to navigate through pages, submitting forms, and caching local
|
7
|
+
responses.
|
8
|
+
|
9
|
+
The current version is 0.0.1.
|
10
|
+
|
11
|
+
**THIS CODE IS TERRIBLE AND EXPERIMENTAL!!!!!1 CONSIDER IT A BRAIN DUMP. THERE ARE NO TESTS. THERE ARE NO COMMENTS. THE CODE IS HORRIBLE. PLEASE DON'T USE THIS FOR ANYTHING YET.**
|
12
|
+
|
13
|
+
Find out more at [the hateoas homepage][homepage].
|
14
|
+
|
15
|
+
Installing
|
16
|
+
==========
|
17
|
+
|
18
|
+
Become a HATEr by using Rubygems:
|
19
|
+
|
20
|
+
```
|
21
|
+
gem install hateoas
|
22
|
+
```
|
23
|
+
|
24
|
+
Usage
|
25
|
+
=====
|
26
|
+
|
27
|
+
Primarily, you'll use HATEOAS to help create your own gem to interact with your
|
28
|
+
API. We'll pretend that you're writing an API to your own blogging
|
29
|
+
software, since blogs are the Rails "Hello world" project.
|
30
|
+
|
31
|
+
Right now, HATEOAS assumes that you use XHTML5 to drive your API.
|
32
|
+
|
33
|
+
Configuration
|
34
|
+
-------------
|
35
|
+
|
36
|
+
The first thing you need to do is configure HATEOAS. Congratulations on
|
37
|
+
creating a hypermedia API; it means the configuration is minimal! Simply
|
38
|
+
assign your root URI like this:
|
39
|
+
|
40
|
+
```
|
41
|
+
Hateoas.base_uri = "http://api.hackety-hack.com"
|
42
|
+
```
|
43
|
+
|
44
|
+
HATEOAS has environment variables that make it easy to hit your local copy in
|
45
|
+
development mode. By default, HATEOAS assumes you're using pow, and so it will
|
46
|
+
append '.dev' onto the end of your `base_uri` when it is in development
|
47
|
+
mode. To use something else, set the `development_base_uri`:
|
48
|
+
|
49
|
+
```
|
50
|
+
HATEOAS.develoment_base_uri = "http://localhost:9292"
|
51
|
+
```
|
52
|
+
|
53
|
+
The `HATEOAS_ENV` variable will control which configuration is used. Just like
|
54
|
+
Rails, there are development, test, and production modes.
|
55
|
+
|
56
|
+
In my own APIs, I prefer to use URIs for my rel attributes. If you also do
|
57
|
+
this, there's an optional variable that makes using URIs simpler. Without it,
|
58
|
+
here's how you navigate to the 'new post' page, then the 'new comments'
|
59
|
+
page:
|
60
|
+
|
61
|
+
```
|
62
|
+
Hateoas::DSL.click_link("/rels/new-post")
|
63
|
+
Hateoas::DSL.click_link("/rels/new-comments")
|
64
|
+
```
|
65
|
+
|
66
|
+
And with it:
|
67
|
+
|
68
|
+
```
|
69
|
+
Hateoas.rel_namespace = "rels"
|
70
|
+
|
71
|
+
Hateoas::DSL.click_link("new-post")
|
72
|
+
Hateoas::DSL.click_link("new-comments")
|
73
|
+
```
|
74
|
+
|
75
|
+
Groovy?
|
76
|
+
|
77
|
+
DSL
|
78
|
+
---
|
79
|
+
|
80
|
+
HATEOAS provides a `DSL` module with all of the DSL methods you'll need. You
|
81
|
+
can use these methods in two ways: One is to reference them by using their fully
|
82
|
+
qualified names:
|
83
|
+
|
84
|
+
```
|
85
|
+
Hateoas::DSL.click_link("new-post")
|
86
|
+
```
|
87
|
+
|
88
|
+
Optionally, if you're building your own infrastructure around all of this, you
|
89
|
+
can include the module inside your own class:
|
90
|
+
|
91
|
+
```
|
92
|
+
class MyApi
|
93
|
+
include Hateoas::DSL
|
94
|
+
|
95
|
+
def navigate(path)
|
96
|
+
click_link(path)
|
97
|
+
end
|
98
|
+
end
|
99
|
+
```
|
100
|
+
|
101
|
+
The rest of this documentation will simply use `visit` rather than
|
102
|
+
`Hateoas::DSL.visit`.
|
103
|
+
|
104
|
+
Navigation
|
105
|
+
----------
|
106
|
+
|
107
|
+
If you read the previous section, you've got this one figured out: simply give
|
108
|
+
a rel to the `click_link` method:
|
109
|
+
|
110
|
+
```
|
111
|
+
click_link("new-post")
|
112
|
+
```
|
113
|
+
|
114
|
+
Getting Data Back
|
115
|
+
-----------------
|
116
|
+
|
117
|
+
You can access the data on the current page by using the `current_page`
|
118
|
+
method.
|
119
|
+
|
120
|
+
[homepage]: http://steveklabnik.github.com/cereal
|
data/Rakefile
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
require "bundler/gem_tasks"
|
data/SPEC.md
ADDED
@@ -0,0 +1,146 @@
|
|
1
|
+
|
2
|
+
About
|
3
|
+
=====
|
4
|
+
|
5
|
+
HATEOAS helps you build hypermedia API clients, by providing a simple
|
6
|
+
interface to navigate through pages, submitting forms, and caching local
|
7
|
+
responses.
|
8
|
+
|
9
|
+
The current version is 0.0.1.
|
10
|
+
|
11
|
+
Find out more at [the hateoas homepage][homepage].
|
12
|
+
|
13
|
+
Installing
|
14
|
+
==========
|
15
|
+
|
16
|
+
Become a HATEr by using Rubygems:
|
17
|
+
|
18
|
+
```
|
19
|
+
gem install hateoas
|
20
|
+
```
|
21
|
+
|
22
|
+
Usage
|
23
|
+
=====
|
24
|
+
|
25
|
+
Primarily, you'll use HATEOAS to help create your own gem to interact with your
|
26
|
+
API. We'll pretend that you're writing an API to your own blogging
|
27
|
+
software, since blogs are the Rails "Hello world" project.
|
28
|
+
|
29
|
+
Right now, HATEOAS assumes that you use XHTML5 to drive your API.
|
30
|
+
|
31
|
+
Configuration
|
32
|
+
-------------
|
33
|
+
|
34
|
+
The first thing you need to do is configure HATEOAS. Congratulations on
|
35
|
+
creating a hypermedia API; it means the configuration is minimal! Simply
|
36
|
+
assign your root URI like this:
|
37
|
+
|
38
|
+
```
|
39
|
+
Hateoas.base_uri = "http://api.hackety-hack.com"
|
40
|
+
```
|
41
|
+
|
42
|
+
HATEOAS has environment variables that make it easy to hit your local copy in
|
43
|
+
development mode. By default, HATEOAS assumes you're using pow, and so it will
|
44
|
+
append '.dev' onto the end of your `base_uri` when it is in development
|
45
|
+
mode. To use something else, set the `development_base_uri`:
|
46
|
+
|
47
|
+
```
|
48
|
+
HATEOAS.develoment_base_uri = "http://localhost:9292"
|
49
|
+
```
|
50
|
+
|
51
|
+
The `HATEOAS_ENV` variable will control which configuration is used. Just like
|
52
|
+
Rails, there are development, test, and production modes.
|
53
|
+
|
54
|
+
In my own APIs, I prefer to use URIs for my rel attributes. If you also do
|
55
|
+
this, there's an optional variable that makes using URIs simpler. Without it,
|
56
|
+
here's how you navigate to the 'new post' page, then the 'new comments'
|
57
|
+
page:
|
58
|
+
|
59
|
+
```
|
60
|
+
Hateoas::DSL.click_link("/rels/new-post")
|
61
|
+
Hateoas::DSL.click_link("/rels/new-comments")
|
62
|
+
```
|
63
|
+
|
64
|
+
And with it:
|
65
|
+
|
66
|
+
```
|
67
|
+
Hateoas.rel_namespace = "rels"
|
68
|
+
|
69
|
+
Hateoas::DSL.click_link("new-post")
|
70
|
+
Hateoas::DSL.click_link("new-comments")
|
71
|
+
```
|
72
|
+
|
73
|
+
Groovy?
|
74
|
+
|
75
|
+
DSL
|
76
|
+
---
|
77
|
+
|
78
|
+
HATEOAS provides a `DSL` module with all of the DSL methods you'll need. You
|
79
|
+
can use these methods in two ways: One is to reference them by using their fully
|
80
|
+
qualified names:
|
81
|
+
|
82
|
+
```
|
83
|
+
Hateoas::DSL.click_link("new-post")
|
84
|
+
```
|
85
|
+
|
86
|
+
Optionally, if you're building your own infrastructure around all of this, you
|
87
|
+
can include the module inside your own class:
|
88
|
+
|
89
|
+
```
|
90
|
+
class MyApi
|
91
|
+
include Hateoas::DSL
|
92
|
+
|
93
|
+
def navigate(path)
|
94
|
+
click_link(path)
|
95
|
+
end
|
96
|
+
end
|
97
|
+
```
|
98
|
+
|
99
|
+
The rest of this documentation will simply use `visit` rather than
|
100
|
+
`Hateoas::DSL.visit`.
|
101
|
+
|
102
|
+
Navigation
|
103
|
+
----------
|
104
|
+
|
105
|
+
If you read the previous section, you've got this one figured out: simply give
|
106
|
+
a rel to the `click_link` method:
|
107
|
+
|
108
|
+
```
|
109
|
+
click_link("new-post")
|
110
|
+
```
|
111
|
+
|
112
|
+
Getting Data Back
|
113
|
+
-----------------
|
114
|
+
|
115
|
+
You can access the data on the current page by using the `current_page`
|
116
|
+
method.
|
117
|
+
|
118
|
+
Forms
|
119
|
+
-----
|
120
|
+
|
121
|
+
There are a few methods to interact with forms:
|
122
|
+
|
123
|
+
```
|
124
|
+
fill_in('First Name', :with => 'John')
|
125
|
+
fill_in('Password', :with => 'Seekrit')
|
126
|
+
fill_in('Description', :with => 'Really Long Text...')
|
127
|
+
choose('A Radio Button')
|
128
|
+
check('A Checkbox')
|
129
|
+
uncheck('A Checkbox')
|
130
|
+
attach_file('Image', '/path/to/image.jpg')
|
131
|
+
select('Option', :from => 'Select Box')
|
132
|
+
```
|
133
|
+
|
134
|
+
Caching
|
135
|
+
-------
|
136
|
+
|
137
|
+
HATEOAS includes a client-side cache, and respects HTTP caching directives.
|
138
|
+
This helps with performance, and keeps network connections down.
|
139
|
+
|
140
|
+
Authorization
|
141
|
+
-------------
|
142
|
+
|
143
|
+
Authentication
|
144
|
+
--------------
|
145
|
+
|
146
|
+
[homepage]: http://steveklabnik.github.com/cereal
|
data/hateoas.gemspec
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
# -*- encoding: utf-8 -*-
|
2
|
+
$:.push File.expand_path("../lib", __FILE__)
|
3
|
+
require "hateoas/version"
|
4
|
+
|
5
|
+
Gem::Specification.new do |s|
|
6
|
+
s.name = "hateoas"
|
7
|
+
s.version = Hateoas::VERSION
|
8
|
+
s.authors = ["Steve Klabnik"]
|
9
|
+
s.email = ["steve@steveklabnik.com"]
|
10
|
+
s.homepage = "http://steveklabnik.github.com/hateoas"
|
11
|
+
s.summary = %q{Build easy clients for Hypermedia APIs.}
|
12
|
+
s.description = %q{A set of tools to help build clients for Hypermedia APIs.}
|
13
|
+
|
14
|
+
s.files = `git ls-files`.split("\n")
|
15
|
+
s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
|
16
|
+
s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
|
17
|
+
s.require_paths = ["lib"]
|
18
|
+
|
19
|
+
s.add_dependency "mechanize"
|
20
|
+
|
21
|
+
s.add_development_dependency "rspec"
|
22
|
+
end
|
data/lib/hateoas.rb
ADDED
@@ -0,0 +1,43 @@
|
|
1
|
+
require 'hateoas/version'
|
2
|
+
require 'open-uri'
|
3
|
+
require 'mechanize'
|
4
|
+
|
5
|
+
module Hateoas
|
6
|
+
class << self
|
7
|
+
attr_accessor :rel_namespace
|
8
|
+
attr_writer :base_uri, :current_state
|
9
|
+
|
10
|
+
def base_uri
|
11
|
+
if ENV['HATEOAS_ENV'] == "development"
|
12
|
+
development_base_uri || "#{@base_uri}.dev"
|
13
|
+
else
|
14
|
+
@base_uri
|
15
|
+
end
|
16
|
+
end
|
17
|
+
|
18
|
+
def current_page
|
19
|
+
current_state.body
|
20
|
+
end
|
21
|
+
|
22
|
+
def current_state
|
23
|
+
@current_state ||= user_agent.get(base_uri)
|
24
|
+
end
|
25
|
+
|
26
|
+
def user_agent
|
27
|
+
@user_agent ||= Mechanize.new
|
28
|
+
end
|
29
|
+
|
30
|
+
end
|
31
|
+
|
32
|
+
module DSL
|
33
|
+
extend self
|
34
|
+
|
35
|
+
def click_link(rel)
|
36
|
+
if Hateoas.rel_namespace
|
37
|
+
rel = "/#{Hateoas.rel_namespace}/#{rel}"
|
38
|
+
end
|
39
|
+
|
40
|
+
Hateoas.current_state = Hateoas.user_agent.click(Hateoas.current_state.links.find{|l| l.attributes["rel"] == rel })
|
41
|
+
end
|
42
|
+
end
|
43
|
+
end
|
metadata
ADDED
@@ -0,0 +1,100 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: hateoas
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
hash: 29
|
5
|
+
prerelease:
|
6
|
+
segments:
|
7
|
+
- 0
|
8
|
+
- 0
|
9
|
+
- 1
|
10
|
+
version: 0.0.1
|
11
|
+
platform: ruby
|
12
|
+
authors:
|
13
|
+
- Steve Klabnik
|
14
|
+
autorequire:
|
15
|
+
bindir: bin
|
16
|
+
cert_chain: []
|
17
|
+
|
18
|
+
date: 2011-11-06 00:00:00 Z
|
19
|
+
dependencies:
|
20
|
+
- !ruby/object:Gem::Dependency
|
21
|
+
name: mechanize
|
22
|
+
prerelease: false
|
23
|
+
requirement: &id001 !ruby/object:Gem::Requirement
|
24
|
+
none: false
|
25
|
+
requirements:
|
26
|
+
- - ">="
|
27
|
+
- !ruby/object:Gem::Version
|
28
|
+
hash: 3
|
29
|
+
segments:
|
30
|
+
- 0
|
31
|
+
version: "0"
|
32
|
+
type: :runtime
|
33
|
+
version_requirements: *id001
|
34
|
+
- !ruby/object:Gem::Dependency
|
35
|
+
name: rspec
|
36
|
+
prerelease: false
|
37
|
+
requirement: &id002 !ruby/object:Gem::Requirement
|
38
|
+
none: false
|
39
|
+
requirements:
|
40
|
+
- - ">="
|
41
|
+
- !ruby/object:Gem::Version
|
42
|
+
hash: 3
|
43
|
+
segments:
|
44
|
+
- 0
|
45
|
+
version: "0"
|
46
|
+
type: :development
|
47
|
+
version_requirements: *id002
|
48
|
+
description: A set of tools to help build clients for Hypermedia APIs.
|
49
|
+
email:
|
50
|
+
- steve@steveklabnik.com
|
51
|
+
executables: []
|
52
|
+
|
53
|
+
extensions: []
|
54
|
+
|
55
|
+
extra_rdoc_files: []
|
56
|
+
|
57
|
+
files:
|
58
|
+
- .gitignore
|
59
|
+
- Gemfile
|
60
|
+
- README.md
|
61
|
+
- Rakefile
|
62
|
+
- SPEC.md
|
63
|
+
- hateoas.gemspec
|
64
|
+
- lib/hateoas.rb
|
65
|
+
- lib/hateoas/version.rb
|
66
|
+
homepage: http://steveklabnik.github.com/hateoas
|
67
|
+
licenses: []
|
68
|
+
|
69
|
+
post_install_message:
|
70
|
+
rdoc_options: []
|
71
|
+
|
72
|
+
require_paths:
|
73
|
+
- lib
|
74
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
75
|
+
none: false
|
76
|
+
requirements:
|
77
|
+
- - ">="
|
78
|
+
- !ruby/object:Gem::Version
|
79
|
+
hash: 3
|
80
|
+
segments:
|
81
|
+
- 0
|
82
|
+
version: "0"
|
83
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
84
|
+
none: false
|
85
|
+
requirements:
|
86
|
+
- - ">="
|
87
|
+
- !ruby/object:Gem::Version
|
88
|
+
hash: 3
|
89
|
+
segments:
|
90
|
+
- 0
|
91
|
+
version: "0"
|
92
|
+
requirements: []
|
93
|
+
|
94
|
+
rubyforge_project:
|
95
|
+
rubygems_version: 1.8.10
|
96
|
+
signing_key:
|
97
|
+
specification_version: 3
|
98
|
+
summary: Build easy clients for Hypermedia APIs.
|
99
|
+
test_files: []
|
100
|
+
|