Skip to content
Newer
Older
100644 237 lines (162 sloc) 7.29 KB
a2008e6 @mattetti initial version of the gem + generator
authored Apr 27, 2012
1 # Weasel Diesel Sinatra
b4bea30 @mattetti initial commit
authored Apr 27, 2012
2
a2008e6 @mattetti initial version of the gem + generator
authored Apr 27, 2012
3 Weasel-Diesel Sinatra app gem, allowing you to generate/update sinatra apps using the Weasel Diesel DSL
4
5
6 ## Installation
7
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
8 $ gem install 'wd_sinatra'
9
a2008e6 @mattetti initial version of the gem + generator
authored Apr 27, 2012
10 ## Usage
11
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
12 ### App generation
13
14 Once the gem is installed, you can use the generator to create a new
15 app. Go to the location where you want to generate a new app and type
16 the following command (replace `<app_name>` by the name you want to
17 application to have):
18
19 $ wd_sinatra <app_name>
20
21 Check the newly generated app
22
23 $ cd <app_name>
24
25 You'll need bundler to install the dependencies:
26
27 $ gem install bundler
28 $ bundle install
29
30 ### Starting the server
31
32 The app is now ready to use, to start it you can use rack:
33
34 $ bundle exec rackup
35
36 This will start the server on port 9292 and the default GET `/hello_world` service will be available at: `http://localhost:9292/hello_world'.
37
38 Note that the code won't be reloading automatically in the server when
39 you make a modification to the source code. For that, you might want to
40 use Puma + [Guard](https://github.com/jc00ke/guard-puma) or another tool that allows you to do that.
41 While it's a nice feature to have, a lot of developers like to do that
42 differently and it seems more sensitive to let them pick the way they
43 like the most.
44
aece611 @mattetti added a service generator (thanks @drnic) and bumped the gem version
authored Jun 14, 2012
45
46 ### Generating a new service
47
48 You need to have thor installed for that, you might want to add it yo
49 your gemfile.
50
51 $ thor :service get /foo/bar foo_bar.rb
52
53 This command will create a service and a failing test for it.
54
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
55 ### Console
56
57 $ bundle exec bin/console
58
59 The console mode is like the server mode but without the server only
60 concerns such as the sinatra routes config and Rack middleware.
61
72d42d9 @mattetti misc small settings improvements
authored Jun 13, 2012
62 If your users also want `script/console`, add the file, chmod +x it and
63 use the following code:
64
65 ```bash
66 #!/bin/bash
67 # Run bin/console for those who like the old Rails way.
68 abspath=$(cd ${0%/*} && echo $PWD/${0##*/})
69 $abspath/../../bin/console
70 ```
71
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
72 ### Documentation generation
73
74 $ rake doc:services
75
76 To generate documentation for the APIs you created in the api folder.
77
78 ### Testing
79
4b5be1e @mattetti udpated documentation
authored May 14, 2012
80 Helpers to test your apps are provided. When you generate your first
81 app, you will see a first example using minitest:
82
83 ```ruby
84 class HelloWorldIntegrationTest < MiniTest::Unit::TestCase
85
86 def test_default_response
87 TestApi.get "/hello_world"
88 assert_api_response
89 assert_equal "Hello World", TestApi.json_response['message']
90 assert Time.parse(TestApi.json_response['at']) < Time.now
91 end
92
93 def test_customized_response
94 TestApi.get "/hello_world", :name => "Matt"
95 assert_api_response
96 assert_equal "Hello Matt", TestApi.json_response['message']
97 assert Time.parse(TestApi.json_response['at']) < Time.now
98 end
99
100 end
101 ```
102
103 The `TestApi` module is used to call a service. The call will go through
104 the entire app stack including middleware.
105 You can then look at the response object via the `TestApi` module using
106 one of the many provided methods such as `last_response`,
107 `json_response` and then methods on `last_response` provided by [Rack](http://rack.rubyforge.org/doc/Rack/MockResponse.html):
108
109 * status
110 * headers
111 * body
112 * errors
113
114 The `TestApi` interface allows you to dispatch all the calls, and to
115 send custom parameters and headers, set cookies and everything you need to do proper integration
116 tests.
117
118 Because we opted to describe our responses, and this framework is based
119 on the concept that we want to communicate about our apis, it is
120 critical to test the service responses. For that, a JSON response helper
121 is provided (testunit/minitest only for now) so you can easily check
122 that the structure of the response matches the description.
123
124 This is what the `assert_api_response` helper does.
125
126 This helper is to be used after you dispatched an API call.
127 The last response is being analyzed and the JSON structure should match
128 the description provided in the service.
129 Note that this helper doesn't check the content of the structure, that
130 is something you need to do yourself with custom tests as shown in the
131 example.
132
133 ### Tips
134
135 When dispatching a test api call using an url with a placeholder such as
136 `/people/:id', you need to pass the id as a param and the url will be
137 properly composed:
138
139 ```ruby
140 TestApi.post '/people/:id', :id => 123
141 ```
142
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
143 ## Writing a service
144
276e961 @mattetti added a params_exception_handler hook
authored May 14, 2012
145 TODO see Weasel Diesel for now and the generated service example.
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
146
147 ## Config and hooks
148
d12aa2d @mattetti getting ready for a 0.0.1 gem release
authored Apr 27, 2012
149 ### app.rb
150
151 The `config/app.rb` file is being required after the environment is set
152 but before the models are loaded. This is the perfect place to load
153 custom libraries and set your datastore.
154
155 This is where you will for instance load ActiveRecord and set your DB
156 connection.
157
158 ### Environments
159
160 The files in `config/environments` can
161 be used to set environment specific configuration or other.
162 If you add a new environment such as staging, you can add a `staging.rb`
163 file in the environments folder that will only get required when running
164 in this env mode.
165 Whatever the environment is, the `config/environments/default.rb` is
166 being required before the specific env file.
167
168 ### Hooks
169
276e961 @mattetti added a params_exception_handler hook
authored May 14, 2012
170 The request dispatcher offers a fews hooks which you can see demonstrated in
d12aa2d @mattetti getting ready for a 0.0.1 gem release
authored Apr 27, 2012
171 `config/hooks.rb`.
172
173 * `params_preprocessor_hook(params)`
174 * `params_postprocessor_hook(params)`
276e961 @mattetti added a params_exception_handler hook
authored May 14, 2012
175 * `params_exception_handler(exception)`
d12aa2d @mattetti getting ready for a 0.0.1 gem release
authored Apr 27, 2012
176 * `pre_dispatch_hook`
177
178 The two first hooks are used to process the params and when implemented
179 are expected to return the params that will be used in the request.
180
276e961 @mattetti added a params_exception_handler hook
authored May 14, 2012
181 The `params_exception_handler` hook allows you to overwrite the default
182 exception handling happening when an exception is raised while handling
183 the params (pre procssing, validation or post processing).
184
d12aa2d @mattetti getting ready for a 0.0.1 gem release
authored Apr 27, 2012
185 The `pre_dispatch_hook` is called just before the request is dispatched
186 to the service implementation. This is where you might want to implement
187 an authentication verification system for instance.
188
428d1ab @mattetti added a post dispatch hook
authored Jun 28, 2012
189 The `post_dispatch_hook` is called, as you might have guessed it, after
190 the response is dispatched but before it gets sent back to the client.
191
276e961 @mattetti added a params_exception_handler hook
authored May 14, 2012
192 These hooks have access to the entire request context, including the
d12aa2d @mattetti getting ready for a 0.0.1 gem release
authored Apr 27, 2012
193 `service` being called. You can use the service `extra` option to set
194 some custom settings that can then be used in this pre dispatch hook.
195
196 In the default generated application, a body parser is provided to parse
197 JSON requests when the HTTP verb is PUT, POST or DELETE. The json parser is set by default to use the `JSON` module but you might want to change it to use Yajl for instance.
198 To do that, edit the `config/hooks.rb` file and change the following:
199
200 ```ruby
201 BodyParser.json_parser = JSON
202 ```
203
204 to:
205
206 ```ruby
207 BodyParser.json_parser = Yajl::Parser
208 ```
209
210 Of course, you'll need to require `Yajl` first and add it to your
211 Gemfile if you want to use Bundler.
212
213
9c86430 @mattetti updated doc and fixed minor issues
authored Apr 27, 2012
214
215 ## Using an ORM
216
d12aa2d @mattetti getting ready for a 0.0.1 gem release
authored Apr 27, 2012
217 TODO: see https://github.com/mattetti/sinatra-web-api-example/ for now
218 for an example of setting up ActiveRecord.
219 Eventually the generator will take an option to generate an AR, DM or
220 other ORM template.
a2008e6 @mattetti initial version of the gem + generator
authored Apr 27, 2012
221
9dee733 @mattetti added gem dependencies
authored Apr 27, 2012
222 ## Update
223
224 To update your app, just update your gem dependency on `wd_sinatra`, you
225 can also compare the difference between your app and a freshly generated
226 app by trying to generate a new app named the same as your old app.
227 The generator will detect conflicts and let you pick an action (diff,
228 overwrite, ignore...)
229
a2008e6 @mattetti initial version of the gem + generator
authored Apr 27, 2012
230 ## Contributing
231
232 1. Fork it
233 2. Create your feature branch (`git checkout -b my-new-feature`)
234 3. Commit your changes (`git commit -am 'Added some feature'`)
235 4. Push to the branch (`git push origin my-new-feature`)
236 5. Create new Pull Request
Something went wrong with that request. Please try again.