restrack 0.1.1 → 0.1.2
Sign up to get free protection for your applications and to get access to all the features.
- data/README.markdown +229 -0
- data/lib/restrack/support.rb +1 -1
- data/lib/restrack/version.rb +1 -1
- data/restrack.gemspec +14 -15
- metadata +16 -47
- data/README.rdoc +0 -196
data/README.markdown
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# RESTRack - serving JSON at REST with pleasure.
|
|
2
|
+
|
|
3
|
+
## Description:
|
|
4
|
+
RESTRack is a [Rack](http://rack.rubyforge.org/)-based [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93View%E2%80%93Controller)
|
|
5
|
+
framework that makes it extremely easy to develop [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)ful
|
|
6
|
+
data services. It is inspired by Rails, and follows a few of its conventions. But it has no routes file, routing
|
|
7
|
+
relationships are done through supplying custom code blocks to class methods such as "has\_relationship\_to" or
|
|
8
|
+
"has\_mapped\_relationships\_to".
|
|
9
|
+
|
|
10
|
+
RESTRack aims at being lightweight and easy to use. It will automatically render JSON and XML for the data
|
|
11
|
+
structures you return in your actions \(any structure parsable by the "[json](http://flori.github.com/json/)" and
|
|
12
|
+
"[xml-simple](https://github.com/maik/xml-simple)" gems, respectively\).
|
|
13
|
+
|
|
14
|
+
If you supply a view for a controller action, you do that using a builder file. Builder files are stored in the
|
|
15
|
+
view directory grouped by controller name subdirectories \(`view/<controller>/<action>.xml.builder`\). XML format
|
|
16
|
+
requests will then render the view template with the builder gem, rather than generating XML with XmlSimple.
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
## Installation:
|
|
20
|
+
### Using [RubyGems](http://rubygems.org):
|
|
21
|
+
<sudo> gem install restrack
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## Why RESTRack when there is Rails?
|
|
25
|
+
[Rails](http://rubyonrails.org/) is a powerful tool for full web applications. RESTRack is targeted at making
|
|
26
|
+
development of lightweight data services as easy as possible, while still giving you a performant and extensible
|
|
27
|
+
framework. The primary goal of of the development of RESTRack was to add as little as possible to the framework to give
|
|
28
|
+
the web developer a good application space for developing JSON and XML services.
|
|
29
|
+
|
|
30
|
+
Rails 3 instantiates approximately 80K more objects than RESTRack to do a hello world or nothing type response with
|
|
31
|
+
the default setup. Trimming Rails down to just ActionController, by eliminating ActiveRecord, ActionMailer, and
|
|
32
|
+
ActiveResource, it still instantiates over 47K more objects than RESTRack.
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
## CLI Usage:
|
|
36
|
+
### Generate a new service \(FooBar::WebService\)
|
|
37
|
+
- restrack generate service foo\_bar
|
|
38
|
+
- restrack gen serv foo\_bar
|
|
39
|
+
- restrack g s foo\_bar
|
|
40
|
+
|
|
41
|
+
### Generate a new controller \(FooBar::BazController\)
|
|
42
|
+
- restrack generate controller baz
|
|
43
|
+
- restrack gen cont baz
|
|
44
|
+
- restrack g c baz
|
|
45
|
+
|
|
46
|
+
### Generate a new controller that descends from another \(FooBar::NewController < FooBar::BazController\)
|
|
47
|
+
- restrack generate controller new descendant\_from baz
|
|
48
|
+
- restrack g controller new parent baz
|
|
49
|
+
|
|
50
|
+
### Start up a server on default rackup port 9292
|
|
51
|
+
- restrack server
|
|
52
|
+
|
|
53
|
+
### Start up a server on port 3456
|
|
54
|
+
- restrack server 3456
|
|
55
|
+
- restrack s 3456
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
## REST action method names
|
|
59
|
+
All default RESTful controller method names align with their Rails counterparts, with two additional actions being
|
|
60
|
+
supported\(\*\).
|
|
61
|
+
|
|
62
|
+
HTTP Verb: | GET | PUT | POST | DELETE
|
|
63
|
+
Collection URI (/widgets/): | index | replace | create | *drop
|
|
64
|
+
Element URI (/widgets/42): | show | update | *add | destroy
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
## URLs and Controller relationships
|
|
68
|
+
RESTRack enforces a strict URL pattern through the contruct of controller relationships, rather than a routing file.
|
|
69
|
+
Defining a controller for a resource means that you plan to expose that resource to requests to your service.
|
|
70
|
+
Defining a controller relationship means that you plan to expose a path from this resource to another.
|
|
71
|
+
|
|
72
|
+
### "pass\_through\_to"
|
|
73
|
+
An open, or pass-through, path can be defined via the "pass\_through\_to" class method for resource controllers. This
|
|
74
|
+
exposes URL patterns like the following:
|
|
75
|
+
|
|
76
|
+
GET /foo/123/bar/234 <= simple pass-through from Foo 123 to show Bar 234
|
|
77
|
+
GET /foo/123/bar <= simple pass-through from Foo 123 to Bar index
|
|
78
|
+
|
|
79
|
+
### "has\_relationship\_to"
|
|
80
|
+
A direct path to a single related resource's controller can be defined with the "has\_relationship\_to" method. This
|
|
81
|
+
allows you to define a one-to-one relationship from this resource to a related resource, which means that the id of
|
|
82
|
+
the related resource is implied through the id of the caller. The caller has one relation through a custom code block
|
|
83
|
+
passed to "has\_relationship\_to". The code block takes the caller resource's id and evaluates to the relation
|
|
84
|
+
resource's id, for example a PeopleController might define a one-to-one relationship like so:
|
|
85
|
+
|
|
86
|
+
has_relationship_to( :people, :as spouse ) do |id|
|
|
87
|
+
People.find(id).spouse.id
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
This exposes URL patterns like the following:
|
|
91
|
+
|
|
92
|
+
GET /people/Sally/spouse <= direct route to show Sally's spouse
|
|
93
|
+
PUT /people/Henry/spouse <= direct route to update Henry's spouse
|
|
94
|
+
POST /people/Jane/spouse <= direct route to add Jane's spouse
|
|
95
|
+
|
|
96
|
+
### "has\_relationships\_to" and "has\_defined\_relationships\_to"
|
|
97
|
+
A direct path to many related resources' controller can be defined with the "has\_relationships\_to" and
|
|
98
|
+
"has\_defined\_relationships\_to" methods. These allows you to define one-to-many relationships. They work similar to
|
|
99
|
+
"has\_relationship\_to", except that they accept code blocks which evaluate to arrays of related child ids. Each
|
|
100
|
+
resource in the parent's relation list is then accessed through its array index (zero-based) in the URL. An example
|
|
101
|
+
of exposing the list of a People resource's children in this manner follows:
|
|
102
|
+
|
|
103
|
+
has_relationships_to( :people, :as => children ) do |id|
|
|
104
|
+
People.find(id).children.collect {|child| child.id}
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
Which exposes URLs similar to:
|
|
108
|
+
|
|
109
|
+
GET /people/Nancy/children/0 <= direct route to show child 0
|
|
110
|
+
DELETE /people/Robert/children/100 <= direct route to destroy child 100
|
|
111
|
+
|
|
112
|
+
An example of "has\_defined\_relationships\_to":
|
|
113
|
+
|
|
114
|
+
has_defined_relationships_to( :people, :as => children ) do |id|
|
|
115
|
+
People.find(id).children.collect {|child| child.id}
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
exposes URL patterns:
|
|
119
|
+
|
|
120
|
+
GET /people/Nancy/children/George <= route to show child George
|
|
121
|
+
DELETE /people/Robert/children/Jerry <= route to destroy child Jerry
|
|
122
|
+
|
|
123
|
+
### "has\_mapped\_relationships\_to"
|
|
124
|
+
Multiple named one-to-many relationships can be exposed with the "has\_mapped\_relationships\_to" method. This allows
|
|
125
|
+
you to define many named or keyword paths to related resources. The method's code block should accepts the parent id
|
|
126
|
+
and return a hash where the keys are your relationship names and the values are the child resource ids. For example,
|
|
127
|
+
within a PeopleController the following definition:
|
|
128
|
+
|
|
129
|
+
has_mapped_relationships_to( :people ) do |id|
|
|
130
|
+
{
|
|
131
|
+
'father' => People.find(id).father.id,
|
|
132
|
+
'mother' => People.find(id).mother.id,
|
|
133
|
+
'boss' => People.find(id).boss.id,
|
|
134
|
+
'assistant' => People.find(id).assistant.id
|
|
135
|
+
}
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
This would expose the following URL patterns:
|
|
139
|
+
|
|
140
|
+
GET /people/Fred/people/father => show the father of Fred
|
|
141
|
+
PUT /people/Fred/people/assistant => update Fred's assistant
|
|
142
|
+
POST /people/Fred/people/boss => add Fred's boss
|
|
143
|
+
DELETE /people/Luke/people/mother => destroy Luke's father
|
|
144
|
+
|
|
145
|
+
### Setting the data type of the id - "keyed\_with\_type"
|
|
146
|
+
Resource id data types can be defined with the "keyed\_with\_type" class method within resource controllers. The
|
|
147
|
+
default data type of String is used if a different type is not specified.
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
## Logging/Logging Level
|
|
151
|
+
RESTRack outputs to two logs, the standard log (or error log) and the request log. Paths and logging levels for these
|
|
152
|
+
can be configured in `config/constants.yaml`. RESTRack uses Logger from Ruby-stdlib.
|
|
153
|
+
|
|
154
|
+
## XML Serialization
|
|
155
|
+
RESTRack will convert the data structures that your actions return to JSON by default. You can change the default
|
|
156
|
+
by setting :DEFAULT_FORMAT to :XML in `config/constants.yml`.
|
|
157
|
+
|
|
158
|
+
### With XmlSimple
|
|
159
|
+
RESTRack will attempt to serialize the data structures that your action methods return automatically using the
|
|
160
|
+
xml-simple gem.
|
|
161
|
+
|
|
162
|
+
### With Builder
|
|
163
|
+
Custom XML serialization can be done by providing Builder gem templates in `views/<controller>/<action>.xml.builder`.
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
## Inputs
|
|
167
|
+
|
|
168
|
+
### Query string parameters
|
|
169
|
+
Available to controllers in the @params instance variable.
|
|
170
|
+
|
|
171
|
+
### POST data
|
|
172
|
+
Available to controllers in the @input instance variable.
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
## Constant Definition (config/constants.yaml)
|
|
176
|
+
|
|
177
|
+
### Required Configuration Settings
|
|
178
|
+
#### :LOG
|
|
179
|
+
Sets the location of the error log.
|
|
180
|
+
|
|
181
|
+
#### :REQUEST\_LOG
|
|
182
|
+
Sets the location of the request log.
|
|
183
|
+
|
|
184
|
+
#### :LOG\_LEVEL
|
|
185
|
+
Sets the the logging level of the error log, based on the Ruby Logger object. Supply these as a symbol, with valid
|
|
186
|
+
values being :DEBUG, :INFO, :WARN, etc.
|
|
187
|
+
|
|
188
|
+
#### :REQUEST\_LOG\_LEVEL
|
|
189
|
+
Sets the the logging level of the request log, similar to :LOG_LEVEL.
|
|
190
|
+
|
|
191
|
+
### Optional Configuration Settings
|
|
192
|
+
#### :DEFAULT\_FORMAT
|
|
193
|
+
Sets the default format for the response. This is the format that the response will take if no extension is appended to
|
|
194
|
+
the request string (i.e. /foo/123 rather than /foo/123.xml). Services will have a default format of JSON if this
|
|
195
|
+
configuration option is not defined.
|
|
196
|
+
|
|
197
|
+
#### :DEFAULT\_RESOURCE
|
|
198
|
+
Set this option in config/constants.yaml to use an implied root resource controller.
|
|
199
|
+
|
|
200
|
+
:DEFAULT_RESOURCE: foo
|
|
201
|
+
# /foo/123 could be accessed with /123
|
|
202
|
+
# /foo could be accessed with /
|
|
203
|
+
|
|
204
|
+
#### :ROOT\_RESOURCE\_ACCEPT
|
|
205
|
+
:ROOT_RESOURCE_ACCEPT: [ 'foo', 'bar' ]
|
|
206
|
+
# defines an array of resources that can be accessed (without being proxied through another relation).
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
#### :ROOT\_RESOURCE\_DENY
|
|
210
|
+
:ROOT_RESOURCE_DENY: [ 'baz' ]
|
|
211
|
+
# defines an array of resources that cannot be accessed without proxying though another controller.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
## License:
|
|
215
|
+
|
|
216
|
+
Copyright (c) 2010 Chris St. John
|
|
217
|
+
|
|
218
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
|
|
219
|
+
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
|
|
220
|
+
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
|
|
221
|
+
persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
222
|
+
|
|
223
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
|
|
224
|
+
Software.
|
|
225
|
+
|
|
226
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
|
|
227
|
+
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
228
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
229
|
+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/lib/restrack/support.rb
CHANGED
data/lib/restrack/version.rb
CHANGED
data/restrack.gemspec
CHANGED
|
@@ -9,21 +9,20 @@ Gem::Specification.new do |s|
|
|
|
9
9
|
s.authors = ['Chris St. John']
|
|
10
10
|
s.email = ['chris@stjohnstudios.com']
|
|
11
11
|
s.homepage = 'http://github.com/stjohncj/RESTRack'
|
|
12
|
-
s.summary = %q{A lightweight MVC framework developed specifically for JSON and XML REST services.}
|
|
13
|
-
s.description = %q{
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
XmlSimple.}
|
|
12
|
+
s.summary = %q{A lightweight MVC framework developed specifically for JSON (and XML) REST services.}
|
|
13
|
+
s.description = %q{
|
|
14
|
+
RESTRack is a Rack-based MVC framework that makes it extremely easy to develop RESTful data services. It is inspired by
|
|
15
|
+
Rails, and follows a few of its conventions. But it has no routes file, routing relationships are done through
|
|
16
|
+
supplying custom code blocks to class methods such as "has_relationship_to" or "has_mapped_relationships_to".
|
|
17
|
+
|
|
18
|
+
RESTRack aims at being lightweight and easy to use. It will automatically render JSON and XML for the data
|
|
19
|
+
structures you return in your actions (any structure parsable by the "json" and
|
|
20
|
+
"xml-simple" gems, respectively).
|
|
21
|
+
|
|
22
|
+
If you supply a view for a controller action, you do that using a builder file. Builder files are stored in the
|
|
23
|
+
view directory grouped by controller name subdirectories (`view/<controller>/<action>.xml.builder`). XML format
|
|
24
|
+
requests will then render the view template with the builder gem, rather than generating XML with XmlSimple.
|
|
25
|
+
}
|
|
27
26
|
|
|
28
27
|
s.rubyforge_project = "restrack"
|
|
29
28
|
|
metadata
CHANGED
|
@@ -1,12 +1,8 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: restrack
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
prerelease:
|
|
5
|
-
|
|
6
|
-
- 0
|
|
7
|
-
- 1
|
|
8
|
-
- 1
|
|
9
|
-
version: 0.1.1
|
|
4
|
+
prerelease:
|
|
5
|
+
version: 0.1.2
|
|
10
6
|
platform: ruby
|
|
11
7
|
authors:
|
|
12
8
|
- Chris St. John
|
|
@@ -14,7 +10,7 @@ autorequire:
|
|
|
14
10
|
bindir: bin
|
|
15
11
|
cert_chain: []
|
|
16
12
|
|
|
17
|
-
date: 2011-02-
|
|
13
|
+
date: 2011-02-13 00:00:00 -05:00
|
|
18
14
|
default_executable:
|
|
19
15
|
dependencies:
|
|
20
16
|
- !ruby/object:Gem::Dependency
|
|
@@ -25,8 +21,6 @@ dependencies:
|
|
|
25
21
|
requirements:
|
|
26
22
|
- - ">="
|
|
27
23
|
- !ruby/object:Gem::Version
|
|
28
|
-
segments:
|
|
29
|
-
- 0
|
|
30
24
|
version: "0"
|
|
31
25
|
type: :runtime
|
|
32
26
|
version_requirements: *id001
|
|
@@ -38,8 +32,6 @@ dependencies:
|
|
|
38
32
|
requirements:
|
|
39
33
|
- - ">="
|
|
40
34
|
- !ruby/object:Gem::Version
|
|
41
|
-
segments:
|
|
42
|
-
- 0
|
|
43
35
|
version: "0"
|
|
44
36
|
type: :runtime
|
|
45
37
|
version_requirements: *id002
|
|
@@ -51,8 +43,6 @@ dependencies:
|
|
|
51
43
|
requirements:
|
|
52
44
|
- - ">="
|
|
53
45
|
- !ruby/object:Gem::Version
|
|
54
|
-
segments:
|
|
55
|
-
- 0
|
|
56
46
|
version: "0"
|
|
57
47
|
type: :runtime
|
|
58
48
|
version_requirements: *id003
|
|
@@ -64,8 +54,6 @@ dependencies:
|
|
|
64
54
|
requirements:
|
|
65
55
|
- - ">="
|
|
66
56
|
- !ruby/object:Gem::Version
|
|
67
|
-
segments:
|
|
68
|
-
- 0
|
|
69
57
|
version: "0"
|
|
70
58
|
type: :runtime
|
|
71
59
|
version_requirements: *id004
|
|
@@ -77,10 +65,6 @@ dependencies:
|
|
|
77
65
|
requirements:
|
|
78
66
|
- - ">="
|
|
79
67
|
- !ruby/object:Gem::Version
|
|
80
|
-
segments:
|
|
81
|
-
- 1
|
|
82
|
-
- 0
|
|
83
|
-
- 13
|
|
84
68
|
version: 1.0.13
|
|
85
69
|
type: :runtime
|
|
86
70
|
version_requirements: *id005
|
|
@@ -92,8 +76,6 @@ dependencies:
|
|
|
92
76
|
requirements:
|
|
93
77
|
- - ">="
|
|
94
78
|
- !ruby/object:Gem::Version
|
|
95
|
-
segments:
|
|
96
|
-
- 0
|
|
97
79
|
version: "0"
|
|
98
80
|
type: :runtime
|
|
99
81
|
version_requirements: *id006
|
|
@@ -105,8 +87,6 @@ dependencies:
|
|
|
105
87
|
requirements:
|
|
106
88
|
- - ">="
|
|
107
89
|
- !ruby/object:Gem::Version
|
|
108
|
-
segments:
|
|
109
|
-
- 0
|
|
110
90
|
version: "0"
|
|
111
91
|
type: :runtime
|
|
112
92
|
version_requirements: *id007
|
|
@@ -118,26 +98,19 @@ dependencies:
|
|
|
118
98
|
requirements:
|
|
119
99
|
- - ">="
|
|
120
100
|
- !ruby/object:Gem::Version
|
|
121
|
-
segments:
|
|
122
|
-
- 0
|
|
123
101
|
version: "0"
|
|
124
102
|
type: :runtime
|
|
125
103
|
version_requirements: *id008
|
|
126
|
-
description:
|
|
127
|
-
RESTRack is a Rack
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
respectively).
|
|
137
|
-
If you supply a view for a controller action, you do that using a builder
|
|
138
|
-
file (view/<controller>/<action>.xml.builder). XML format requests will then
|
|
139
|
-
render the view template with the builder gem, rather than generating XML with
|
|
140
|
-
XmlSimple.
|
|
104
|
+
description: "\n\
|
|
105
|
+
RESTRack is a Rack-based MVC framework that makes it extremely easy to develop RESTful data services. It is inspired by\n\
|
|
106
|
+
Rails, and follows a few of its conventions. But it has no routes file, routing relationships are done through\n\
|
|
107
|
+
supplying custom code blocks to class methods such as \"has_relationship_to\" or \"has_mapped_relationships_to\".\n\n\
|
|
108
|
+
RESTRack aims at being lightweight and easy to use. It will automatically render JSON and XML for the data\n\
|
|
109
|
+
structures you return in your actions (any structure parsable by the \"json\" and\n\
|
|
110
|
+
\"xml-simple\" gems, respectively).\n\n\
|
|
111
|
+
If you supply a view for a controller action, you do that using a builder file. Builder files are stored in the\n\
|
|
112
|
+
view directory grouped by controller name subdirectories (`view/<controller>/<action>.xml.builder`). XML format\n\
|
|
113
|
+
requests will then render the view template with the builder gem, rather than generating XML with XmlSimple.\n "
|
|
141
114
|
email:
|
|
142
115
|
- chris@stjohnstudios.com
|
|
143
116
|
executables:
|
|
@@ -148,7 +121,7 @@ extra_rdoc_files: []
|
|
|
148
121
|
|
|
149
122
|
files:
|
|
150
123
|
- Gemfile
|
|
151
|
-
- README.
|
|
124
|
+
- README.markdown
|
|
152
125
|
- Rakefile
|
|
153
126
|
- bin/restrack
|
|
154
127
|
- lib/restrack.rb
|
|
@@ -223,24 +196,20 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
223
196
|
requirements:
|
|
224
197
|
- - ">="
|
|
225
198
|
- !ruby/object:Gem::Version
|
|
226
|
-
segments:
|
|
227
|
-
- 0
|
|
228
199
|
version: "0"
|
|
229
200
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
230
201
|
none: false
|
|
231
202
|
requirements:
|
|
232
203
|
- - ">="
|
|
233
204
|
- !ruby/object:Gem::Version
|
|
234
|
-
segments:
|
|
235
|
-
- 0
|
|
236
205
|
version: "0"
|
|
237
206
|
requirements: []
|
|
238
207
|
|
|
239
208
|
rubyforge_project: restrack
|
|
240
|
-
rubygems_version: 1.
|
|
209
|
+
rubygems_version: 1.5.2
|
|
241
210
|
signing_key:
|
|
242
211
|
specification_version: 3
|
|
243
|
-
summary: A lightweight MVC framework developed specifically for JSON and XML REST services.
|
|
212
|
+
summary: A lightweight MVC framework developed specifically for JSON (and XML) REST services.
|
|
244
213
|
test_files:
|
|
245
214
|
- test/sample_app_1/config/constants.yaml
|
|
246
215
|
- test/sample_app_1/controllers/bat_controller.rb
|
data/README.rdoc
DELETED
|
@@ -1,196 +0,0 @@
|
|
|
1
|
-
= RESTRack
|
|
2
|
-
|
|
3
|
-
== Description:
|
|
4
|
-
RESTRack is a Rack-based MVC framework that makes it extremely easy to develop RESTful data services. It is inspired
|
|
5
|
-
by Rails, and follows a few of its conventions. But it has no routes file, routing relationships are done through
|
|
6
|
-
supplying custom code blocks to class methods such as 'has_relationship_to' or 'has_mapped_relationships_to'.
|
|
7
|
-
RESTRack aims at being lightweight and easy to use. It will automatically render JSON and XML for the data
|
|
8
|
-
structures you return in your actions (any structure parsable by the 'json' and 'xml-simple' gems, respectively).
|
|
9
|
-
If you supply a view for a controller action, you do that using a builder file. Builder files are stored in the
|
|
10
|
-
view directory grouped by controller name subdirectories (view/<controller>/<action>.xml.builder). XML format
|
|
11
|
-
requests will then render the view template with the builder gem, rather than generating XML with XmlSimple.
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
== Installation:
|
|
15
|
-
<sudo> gem install restrack
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
== Why RESTRack when there is Rails?
|
|
19
|
-
Rails is a powerful tool for full web applications. RESTRack is targeted at making development of lightweight data
|
|
20
|
-
services as easy as possible, while still giving you a performant and extensible framework. The primary goal of
|
|
21
|
-
of the development of RESTRack was to add as little as possible to the framework to give the web developer a good
|
|
22
|
-
application space for developing JSON and XML services.
|
|
23
|
-
|
|
24
|
-
Rails 3 instantiates approximately 80K more objects than RESTRack to do a hello world or nothing type response with
|
|
25
|
-
the default setup. Trimming Rails down to just ActionController, by eliminating ActiveRecord, ActionMailer, and
|
|
26
|
-
ActiveResource, it still instantiates over 47K more objects than RESTRack.
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
== CLI Usage:
|
|
30
|
-
- restrack generate service foo_bar
|
|
31
|
-
- restrack gen serv foo_bar
|
|
32
|
-
- restrack g s foo_bar
|
|
33
|
-
- restrack generate controller baz
|
|
34
|
-
- restrack gen cont baz
|
|
35
|
-
- restrack g c baz
|
|
36
|
-
- restrack server # default rackup port 9292
|
|
37
|
-
- restrack server 3456
|
|
38
|
-
- restrack s 3456
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
== REST action method names
|
|
42
|
-
All default RESTful controller method names align with their Rails counterparts, with two additional actions being
|
|
43
|
-
supported(*).
|
|
44
|
-
|
|
45
|
-
# HTTP Verb: | GET | PUT | POST | DELETE
|
|
46
|
-
# Collection URI (/widgets/): | index | replace | create | *drop
|
|
47
|
-
# Element URI (/widgets/42): | show | update | *add | destroy
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
== URLs and Controller relationships
|
|
51
|
-
RESTRack enforces a strict URL pattern through the contruct of controller relationships, rather than a routing file.
|
|
52
|
-
Defining a controller for a resource means that you plan to expose that resource to requests to your service.
|
|
53
|
-
Defining a controller relationship means that you plan to expose a path from this resource to another.
|
|
54
|
-
|
|
55
|
-
=== 'pass_through_to'
|
|
56
|
-
An open, or pass-through, path can be defined via the 'pass_through_to' class method for resource controllers. This
|
|
57
|
-
exposes URL patterns like the following:
|
|
58
|
-
GET /foo/123/bar/234 <= simple pass-through from Foo 123 to show Bar 234
|
|
59
|
-
GET /foo/123/bar <= simple pass-through from Foo 123 to Bar index
|
|
60
|
-
|
|
61
|
-
=== 'has_relationship_to'
|
|
62
|
-
A direct path to a single related resource's controller can be defined with the 'has_relationship_to' method. This
|
|
63
|
-
allows you to define a one-to-one relationship from this resource to a related resource, which means that the id of
|
|
64
|
-
the related resource is implied through the id of the caller. The caller has one relation through a custom code block
|
|
65
|
-
passed to 'has_relationship_to'. The code block takes the caller resource's id and evaluates to the relation
|
|
66
|
-
resource's id, for example a PeopleController might define a one-to-one relationship like so:
|
|
67
|
-
has_relationship_to( :people, :as spouse ) do |id|
|
|
68
|
-
People.find(id).spouse.id
|
|
69
|
-
end
|
|
70
|
-
This exposes URL patterns like
|
|
71
|
-
the following:
|
|
72
|
-
GET /people/Sally/spouse <= direct route to show Sally's spouse
|
|
73
|
-
PUT /people/Henry/spouse <= direct route to update Henry's spouse
|
|
74
|
-
POST /people/Jane/spouse <= direct route to add Jane's spouse
|
|
75
|
-
|
|
76
|
-
=== 'has_relationships_to' and 'has_defined_relationships_to'
|
|
77
|
-
A direct path to many related resources' controller can be defined with the 'has_relationships_to' and
|
|
78
|
-
'has_defined_relationships_to' methods. These allows you to define one-to-many relationships. They work similar to
|
|
79
|
-
'has_relationship_to', except that they accept code blocks which evaluate to arrays of related child ids. Each
|
|
80
|
-
resource in the parent's relation list is then accessed through its array index (zero-based) in the URL. An example
|
|
81
|
-
of exposing the list of a People resource's children in this manner follows:
|
|
82
|
-
has_relationships_to( :people, :as => children ) do |id|
|
|
83
|
-
People.find(id).children.collect {|child| child.id}
|
|
84
|
-
end
|
|
85
|
-
GET /people/Nancy/children/0 <= direct route to show child 0
|
|
86
|
-
DELETE /people/Robert/children/100 <= direct route to destroy child 100
|
|
87
|
-
|
|
88
|
-
has_defined_relationships_to( :people, :as => children ) do |id|
|
|
89
|
-
People.find(id).children.collect {|child| child.id}
|
|
90
|
-
end
|
|
91
|
-
GET /people/Nancy/children/George <= direct route to show child 0
|
|
92
|
-
DELETE /people/Robert/children/John <= direct route to destroy child 100
|
|
93
|
-
|
|
94
|
-
=== 'has_mapped_relationships_to'
|
|
95
|
-
Multiple named one-to-many relationships can be exposed with the 'has_mapped_relationships_to' method. This allows
|
|
96
|
-
you to define many named or keyword paths to related resources. The method's code block should accepts the parent id
|
|
97
|
-
and return a hash where the keys are your relationship names and the values are the child resource ids. For example,
|
|
98
|
-
within a PeopleController the following definition:
|
|
99
|
-
has_mapped_relationships_to( :people ) do |id|
|
|
100
|
-
{
|
|
101
|
-
'father' => People.find(id).father.id,
|
|
102
|
-
'mother' => People.find(id).mother.id,
|
|
103
|
-
'boss' => People.find(id).boss.id,
|
|
104
|
-
'assistant' => People.find(id).assistant.id
|
|
105
|
-
}
|
|
106
|
-
end
|
|
107
|
-
This would expose the following URL patterns:
|
|
108
|
-
GET /people/Fred/people/father => show the father of Fred
|
|
109
|
-
PUT /people/Fred/people/assistant => update Fred's assistant
|
|
110
|
-
POST /people/Fred/people/boss => add Fred's boss
|
|
111
|
-
DELETE /people/Luke/people/mother => destroy Luke's father
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
Resource id data types can be defined with the keyed_with_type class method within resource controllers. The
|
|
115
|
-
default data type of String is used if a different type is not specified.
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
== Logging/Logging Level
|
|
119
|
-
RESTRack logs to two logs, the standard log (or error log) and the request log. Paths and logging levels for these
|
|
120
|
-
can be configured in config/constants.yaml. RESTRack uses Logger from Ruby-stdlib.
|
|
121
|
-
|
|
122
|
-
== XML Serialization
|
|
123
|
-
RESTRack will convert the data structures that your actions return to JSON by default. You can change the default
|
|
124
|
-
by setting :DEFAULT_FORMAT to :XML in config/constants.yml.
|
|
125
|
-
|
|
126
|
-
=== With XmlSimple
|
|
127
|
-
RESTRack will attempt to serialize the data structures that your action methods return automatically using the
|
|
128
|
-
xml-simple gem.
|
|
129
|
-
|
|
130
|
-
=== With Builder
|
|
131
|
-
Custom XML serialization can be done by providing Builder gem templates in views/<controller>/<action>.xml.builder
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
== Inputs
|
|
135
|
-
|
|
136
|
-
=== Query string parameters
|
|
137
|
-
Available to controllers in the @params instance variable.
|
|
138
|
-
|
|
139
|
-
=== POST data
|
|
140
|
-
Available to controllers in the @input instance variable.
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
== Constant Definition (config/constants.yaml)
|
|
144
|
-
|
|
145
|
-
=== Required Configuration Settings
|
|
146
|
-
==== :LOG
|
|
147
|
-
Sets the location of the error log.
|
|
148
|
-
|
|
149
|
-
==== :REQUEST_LOG
|
|
150
|
-
Sets the location of the request log.
|
|
151
|
-
|
|
152
|
-
==== :LOG_LEVEL
|
|
153
|
-
Sets the the logging level of the error log, based on the Ruby Logger object. Supply these as a symbol, with valid
|
|
154
|
-
values being :DEBUG, :INFO, :WARN, etc.
|
|
155
|
-
|
|
156
|
-
==== :REQUEST_LOG_LEVEL
|
|
157
|
-
Sets the the logging level of the request log, similar to :LOG_LEVEL.
|
|
158
|
-
|
|
159
|
-
=== Optional Configuration Settings
|
|
160
|
-
==== :DEFAULT_FORMAT
|
|
161
|
-
Sets the default format for the response. This is the format that the response will take if no extension is
|
|
162
|
-
appended to the request string (i.e. /foo/123 rather than /foo/123.xml). Services will have a default format of JSON
|
|
163
|
-
if this configuration option is not defined.
|
|
164
|
-
|
|
165
|
-
==== :DEFAULT_RESOURCE
|
|
166
|
-
Set this option in config/constants.yaml to use an implied root resource controller.
|
|
167
|
-
:DEFAULT_RESOURCE: foo
|
|
168
|
-
# /foo/123 could be accessed with /123
|
|
169
|
-
# /foo could be accessed with /
|
|
170
|
-
|
|
171
|
-
==== :ROOT_RESOURCE_ACCEPT
|
|
172
|
-
:ROOT_RESOURCE_ACCEPT: [ 'foo', 'bar' ]
|
|
173
|
-
defines an array of resources that can be accessed (without being proxied through another relation).
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
==== :ROOT_RESOURCE_DENY
|
|
177
|
-
:ROOT_RESOURCE_DENY: [ 'baz' ]
|
|
178
|
-
defines an array of resources that cannot be accessed without proxying though another controller.
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
== License:
|
|
182
|
-
|
|
183
|
-
Copyright (c) 2010 Chris St. John
|
|
184
|
-
|
|
185
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
|
|
186
|
-
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
|
|
187
|
-
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
|
|
188
|
-
persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
189
|
-
|
|
190
|
-
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
|
|
191
|
-
Software.
|
|
192
|
-
|
|
193
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
|
|
194
|
-
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
195
|
-
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
196
|
-
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|