Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 189 lines (141 sloc) 6.469 kb
50f84c5 @bethesque Updated Travis CI snippet.
bethesque authored
1 # webmachine for Ruby [![Build Status](https://travis-ci.org/seancribbs/webmachine-ruby.svg)](https://travis-ci.org/seancribbs/webmachine-ruby)
b5bafa0 @seancribbs Add a README.
authored
2
b651e5b @seancribbs Complete repository rename and fix a few typos in the docs.
authored
3 webmachine-ruby is a port of
b5bafa0 @seancribbs Add a README.
authored
4 [Webmachine](https://github.com/basho/webmachine), which is written in
5 Erlang. The goal of both projects is to expose interesting parts of
6 the HTTP protocol to your application in a declarative way. This
eb7a6d1 @bethesque Refactoring all the docs. Aiming to make README more concise, and provid...
bethesque authored
7 means that you are less concerned with the procedures involved in handling
8 requests directly and more with describing facts about the resources
9 that make up your application.
10 Webmachine is not a web framework _per se_, but more of a
b5bafa0 @seancribbs Add a README.
authored
11 toolkit for building HTTP-friendly applications. For example, it does
12 not provide a templating engine or a persistence layer; those choices
13 are up to you.
14
39d30fa @jjb move documentation and finding help to above usage
jjb authored
15 ## Features
16
17 * Handles the hard parts of content negotiation, conditional
18 requests, and response codes for you.
eb7a6d1 @bethesque Refactoring all the docs. Aiming to make README more concise, and provid...
bethesque authored
19 * Provides a base resource with points of extension to let you
20 describe what is relevant about your particular resource.
d9e79a4 @lgierth Remove Mongrel adapter
lgierth authored
21 * Supports WEBrick, Reel, HTTPkit, and a Rack shim. Other host
39d30fa @jjb move documentation and finding help to above usage
jjb authored
22 servers are being investigated.
23 * Streaming/chunked response bodies are permitted as Enumerables,
24 Procs, or Fibers!
25 * Unlike the Erlang original, it does real Language negotiation.
eb7a6d1 @bethesque Refactoring all the docs. Aiming to make README more concise, and provid...
bethesque authored
26 * Includes a visual debugger so you can look through the decision
39d30fa @jjb move documentation and finding help to above usage
jjb authored
27 graph to determine how your resources are behaving.
28
29 ## Documentation & Finding Help
30
04006cd @bethesque Updated stuff
bethesque authored
31 * [How it works](/documentation/how-it-works.md) - understand how Webmachine works and the basics of creating a resource.
a1d6490 @bethesque Updated README.md
bethesque authored
32 * [Example resources][example-resources] showing how to implement each HTTP method.
30225ef @bethesque Added routes documentation
bethesque authored
33 * [Routes][routes]
80e49da @bethesque Added documentation on authentication and authorization
bethesque authored
34 * [Authentication and authorization][authentication-and-authorization]
cea3744 @bethesque Added documentation on validation
bethesque authored
35 * [Validation][validation]
499010c @bethesque Reordered Documentation links to put more commonly needed topics at the ...
bethesque authored
36 * [Error handling][error-handling]
37 * [Visual debugger][visual-debugger]
38 * [Configurator][configurator]
7b920a1 @bethesque Added link to Adapters page in Documentation section.
bethesque authored
39 * [Webserver adapters][adapters]
499010c @bethesque Reordered Documentation links to put more commonly needed topics at the ...
bethesque authored
40 * [Versioning APIs][versioning-apis]
39d30fa @jjb move documentation and finding help to above usage
jjb authored
41 * [API documentation](http://rubydoc.info/gems/webmachine/frames/file/README.md)
42 * [Mailing list](mailto:webmachine.rb@librelist.com)
43 * IRC channel #webmachine on freenode
44
b5bafa0 @seancribbs Add a README.
authored
45 ## Getting Started
46
a544c0c @jjb add link to GiddyUp as an example app
jjb authored
47 Below we go through some examples of how to do basic things
48 with webmachine-ruby.
49
794af1e mention Webmachine::Resource.run in README.
Robert authored
50 The first example defines a simple resource that doesn't demo the
51 true power of Webmachine but perhaps gives a feel for how a
52 Webmachine resource might look. `Webmachine::Resource.run` is available
53 to provide for quick prototyping and development. In a real application
54 you will want to configure what path a resource is served from.
55 See the __Router__ section in the README for more details on how to
56 do that.
57
58 There are many other HTTP features exposed to a resource through
59 {Webmachine::Resource::Callbacks}. A callback can alter the outcome
60 of the decision tree Webmachine implements, and the decision tree
61 is what makes Webmachine unique and powerful.
b5bafa0 @seancribbs Add a README.
authored
62
04006cd @bethesque Updated stuff
bethesque authored
63 ### A simple static HTML resource
eb7a6d1 @bethesque Refactoring all the docs. Aiming to make README more concise, and provid...
bethesque authored
64
b5bafa0 @seancribbs Add a README.
authored
65 ```ruby
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
66 require 'webmachine'
a5ba293 @bethesque Router examples
bethesque authored
67
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
68 class MyResource < Webmachine::Resource
69 def to_html
70 "<html><body>Hello, world!</body></html>"
71 end
72 end
794af1e mention Webmachine::Resource.run in README.
Robert authored
73
74 # Start a web server to serve requests via localhost
75 MyResource.run
b5bafa0 @seancribbs Add a README.
authored
76 ```
77
04006cd @bethesque Updated stuff
bethesque authored
78 ### A simple dynamic JSON Resource
a5ba293 @bethesque Router examples
bethesque authored
79
80 ```ruby
81 require 'webmachine'
04006cd @bethesque Updated stuff
bethesque authored
82 require 'widget'
a5ba293 @bethesque Router examples
bethesque authored
83
84 class MyResource < Webmachine::Resource
85
34d65a0 @bethesque Added allowed_methods to README example for clarity.
bethesque authored
86 # GET and HEAD are allowed by default, but are shown here for clarity.
87 def allowed_methods
88 ['GET','HEAD']
a5ba293 @bethesque Router examples
bethesque authored
89 end
90
91 def content_types_provided
92 [['application/json', :to_json]]
93 end
94
34d65a0 @bethesque Added allowed_methods to README example for clarity.
bethesque authored
95 # Return a Truthy or Falsey value
96 def resource_exists?
c29feda @bethesque Explaining why "order doesn't have to matter".
bethesque authored
97 widget
98 end
99
100 def widget
101 @widget ||= Widget.find(request.path_info[:id])
34d65a0 @bethesque Added allowed_methods to README example for clarity.
bethesque authored
102 end
103
a5ba293 @bethesque Router examples
bethesque authored
104 def to_json
c29feda @bethesque Explaining why "order doesn't have to matter".
bethesque authored
105 widget.to_json
a5ba293 @bethesque Router examples
bethesque authored
106 end
107 end
108
109 ```
110
794af1e mention Webmachine::Resource.run in README.
Robert authored
111 ### Router
11051db @seancribbs Witness the power of this fully functional HTTP toolkit.
authored
112
794af1e mention Webmachine::Resource.run in README.
Robert authored
113 The router is used to map a resource to a given path. To map the class `MyResource` to
114 the path `/myresource` you would write something along the lines of:
fa1027b @seancribbs Version bump to 1.0.0.
authored
115
794af1e mention Webmachine::Resource.run in README.
Robert authored
116 ```ruby
117 Webmachine.application.routes do
118 add ['myresource'], MyResource
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
119 end
11051db @seancribbs Witness the power of this fully functional HTTP toolkit.
authored
120
794af1e mention Webmachine::Resource.run in README.
Robert authored
121 # Start a web server to serve requests via localhost
122 Webmachine.application.run
123 ```
b5bafa0 @seancribbs Add a README.
authored
124
04006cd @bethesque Updated stuff
bethesque authored
125 When the resource needs to be mapped with variables that will be passed into the resource, use symbols to identify which path components are variables.
a5ba293 @bethesque Router examples
bethesque authored
126
127 ```ruby
128
129 Webmachine.application.routes do
130 add ['myresource', :id], MyResource
131 end
132
133 ```
134
135 To add more components to the URL mapping, simply add them to the array.
136
137 ```ruby
138
139 Webmachine.application.routes do
140 add ['myparentresource', :parent_id, 'myresource', :id], MyResource
141 end
142
143 ```
144
dd078f6 @bethesque Added link to router page from Router section.
bethesque authored
145 Read more about routing [here][routes].
61599ff @bethesque Added link to router page from Router section.
bethesque authored
146
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
147 ### Application/Configurator
bb37e72 @bernd Add configurator example to the README.
bernd authored
148
a5ba293 @bethesque Router examples
bethesque authored
149 There is a configurator that allows you to set what IP address and port
794af1e mention Webmachine::Resource.run in README.
Robert authored
150 a web server should bind to as well as what web server should serve a
499010c @bethesque Reordered Documentation links to put more commonly needed topics at the ...
bethesque authored
151 webmachine resource. Learn how to configure your application [here][configurator].
bb37e72 @bernd Add configurator example to the README.
bernd authored
152
153
eb7a6d1 @bethesque Refactoring all the docs. Aiming to make README more concise, and provid...
bethesque authored
154 ### Adapters
8e78046 @tarcieri Add Reel to the README's list of supported web servers
tarcieri authored
155
7b920a1 @bethesque Added link to Adapters page in Documentation section.
bethesque authored
156 Webmachine provides adapters for many popular webservers. Learn more [here][adapters].
75a8340 @lgierth Mention adapters in README
lgierth authored
157
fa1027b @seancribbs Version bump to 1.0.0.
authored
158 ### Visual debugger
159
160 It can be hard to understand all of the decisions that Webmachine
161 makes when servicing a request to your resource, which is why we have
499010c @bethesque Reordered Documentation links to put more commonly needed topics at the ...
bethesque authored
162 the "visual debugger". Learn how to configure it [here][visual-debugger].
fa1027b @seancribbs Version bump to 1.0.0.
authored
163
0f2f182 @lgierth Add 'Related libraries' section to README
lgierth authored
164 ## Related libraries
165
3fd6d62 update irwebmachine link.
Robert Gleeson authored
166 * [irwebmachine](https://github.com/robgleeson/irwebmachine) - IRB/Pry debugging of Webmachine applications
0f2f182 @lgierth Add 'Related libraries' section to README
lgierth authored
167 * [webmachine-test](https://github.com/bernd/webmachine-test) - Helpers for testing Webmachine applications
ae8daae @bernd Add link to webmachine-actionview.
bernd authored
168 * [webmachine-linking](https://github.com/petejohanson/webmachine-linking) - Helpers for linking between Resources, and Web Linking
169 * [webmachine-sprockets](https://github.com/lgierth/webmachine-sprockets) - Integration with Sprockets assets packaging system
9b03e1e @bernd Add description for webmachine-actionview.
bernd authored
170 * [webmachine-actionview](https://github.com/rgarner/webmachine-actionview) - Integration of some Rails-style view conventions into Webmachine
5ede988 @seancribbs Add link to jruby-http-kit
authored
171 * [jruby-http-kit](https://github.com/nLight/jruby-http-kit) - Includes an adapter for the Clojure-based Ring library/server
78186fc @seancribbs Add newrelic-webmachine project by request
authored
172 * [newrelic-webmachine](https://github.com/mdub/newrelic-webmachine) - NewRelic instrumentation
0f2f182 @lgierth Add 'Related libraries' section to README
lgierth authored
173
bda6b91 @seancribbs webmachine-ruby is Apache licensed. Thanks for catching that, @strmpnk.
authored
174 ## LICENSE
175
176 webmachine-ruby is licensed under the
177 [Apache v2.0 license](http://www.apache.org/licenses/LICENSE-2.0). See
178 LICENSE for details.
179
a1d6490 @bethesque Updated README.md
bethesque authored
180 [example-resources]: /documentation/examples.md
30225ef @bethesque Added routes documentation
bethesque authored
181 [versioning-apis]: /documentation/versioning-apis.md
7bcba0f @bethesque Added error handling link to README
bethesque authored
182 [routes]: /documentation/routes.md
183 [error-handling]: /documentation/error-handling.md
f1e66dd @bethesque Updated authentication docs.
bethesque authored
184 [authentication-and-authorization]: /documentation/authentication-and-authorization.md
7b920a1 @bethesque Added link to Adapters page in Documentation section.
bethesque authored
185 [adapters]: /documentation/adapters.md
499010c @bethesque Reordered Documentation links to put more commonly needed topics at the ...
bethesque authored
186 [visual-debugger]: /documentation/visual-debugger.md
187 [configurator]: /documentation/configurator.md
cea3744 @bethesque Added documentation on validation
bethesque authored
188 [validation]: /documentation/validation.md
Something went wrong with that request. Please try again.