restrack 0.1.1 → 0.1.2
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/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.
|