webmachine 1.2.2 → 1.3.0

data/documentation/examples.md

@@ -0,0 +1,215 @@
+Imagine an application with an "orders" resource, `OrdersResource`, that represents the collection of orders in the application, and an "order" resource, `OrderResource`, that represents a single order object.
+
+This is how the /orders and /orders/:id routes are mapped to their respective resource classes.
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], OrdersResource
+    add ["orders", :id], OrderResource
+  end
+end
+```
+
+# GET
+* Override `resource_exists?`, `content_types_provided`, `allowed_methods`, and implement the method to render the resource.
+
+Curious as to which order the callbacks will be invoked in? Read why it [doesn't have to matter](#callback-order).
+
+```ruby
+class OrderResource < Webmachine::Resource
+  def allowed_methods
+    ["GET"]
+  end
+
+  def content_types_provided
+    [["application/json", :to_json]]
+  end
+
+  def resource_exists?
+    order
+  end
+
+  def to_json
+    order.to_json
+  end
+
+  private
+
+  def order
+    @order ||= Order.new(params)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+end
+
+```
+
+# POST to create a new resource in a collection
+* Override `post_is_create?` to return true
+* Override `create_path` to return the relative path to the new resource. Note that `create_path` will be called _before_ the content type handler (eg. `from_json`) is called, which means that you need to know the ID before the object has been inserted into the database. This might seem a hassle, but it stops you from exposing your database column IDs to the world, which is a naughty and lazy habit we've all picked up from Rails.
+* The response Content-Type and status will be set for you.
+
+```ruby
+class OrdersResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST"]
+  end
+
+  def content_types_accepted
+    [["application/json", :from_json]]
+  end
+
+  def post_is_create?
+    true
+  end
+
+  def create_path
+    "/orders/#{next_id}"
+  end
+
+  private
+
+  def from_json
+    response.body = new_order.save(next_id).to_json
+  end
+
+  def next_id
+    @id ||= Order.next_id
+  end
+
+  def new_order
+    @new_order ||= Order.new(params)
+  end
+
+  def params
+    JSON.parse(request.body.to_s)
+  end
+end
+```
+
+# POST to perform a task
+* Override `allowed_methods` and `process_post`.  Put all the code to be executed in `process_post`.
+* `process_post` must return true, or the HTTP response code
+* Response headers like Content-Type will need to be set manually.
+
+```ruby
+class DispatchOrderResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST"]
+  end
+
+  def resource_exists?
+    @order = Order.find(id)
+  end
+
+  def process_post
+    @order.dispatch
+    response.headers['Content-Type'] = 'text/plain'
+    response.body = "Successfully dispatched order #{id}"
+    true
+  end
+
+  private
+
+  def id
+    request.path_info[:id]
+  end
+end
+
+```
+
+# PUT
+* Override `resource_exists?`, `content_types_accepted`, `allowed_methods`, and implement the method to create/replace the resource.
+
+```ruby
+class OrderResource < Webmachine::Resource
+
+  def allowed_methods
+    ["PUT"]
+  end
+
+  def content_types_accepted
+    [["application/json", :from_json]]
+  end
+
+  def resource_exists?
+    order
+  end
+
+  def from_json
+    # Remember PUT should replace the entire resource, not merge the attributes! That's what PATCH is for.
+    # It's also why you should not expose your database IDs as your API IDs.
+    order.destroy if order
+    new_order = Order.new(params)
+    new_order.save(id)
+    response.body = new_order.to_json
+  end
+
+  private
+
+  def order
+    @order ||= Order.find(id)
+  end
+
+  def params
+    JSON.parse(request.body.to_s)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+end
+```
+
+# PATCH
+* Webmachine does not currently support PATCH requests. See https://github.com/seancribbs/webmachine-ruby/issues/109 for more information and https://github.com/bethesque/pact_broker/blob/2918814e70bbda14df68598a6a41502a5eac4308/lib/pact_broker/api/resources/pacticipant.rb for a dirty hack to make it work if you need to.
+
+# DELETE
+* Override `resource_exists?` and `delete_resource`
+* `delete_resource` must return true
+* See callbacks.rb for documentation on asynchronous deletes.
+
+```ruby
+class OrderResource < Webmachine::Resource
+
+  def allowed_methods
+    ["DELETE"]
+  end
+
+  def resource_exists?
+    order
+  end
+
+  def delete_resource
+    order.destroy
+    true
+  end
+
+  private
+
+  def order
+    @order ||= Order.find(id)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+
+end
+```
+
+Thanks to [oestrich][oestrich] for putting together the original example. You can see the full source code [here][source].
+
+[oestrich]: https://github.com/oestrich
+[source]: https://gist.github.com/oestrich/3638605
+
+<a name="callback-order">
+## What order are the callbacks invoked in?
+</a>
+
+This question is actually irrelevant if you write your code in a "stateless" way using lazy initialization as the examples do above. As much as possible, think about exposing "facts" about your resource, not writing procedural code that needs to be called in a certain order. See [How it works](/documentation/how-it-works.md) for more information on how the Webmachine state machine works.

data/documentation/how-it-works.md

@@ -0,0 +1,76 @@
+### How it works
+
+Unlike frameworks like Grape and Sinatra, which create a response by running a predefined procedure when a request is received, Webmachine creates an HTTP response by determining a series of "facts" about the resource.
+
+Webmachine is implemented as a [Finite State Machine][diagram]. It uses the facts about your resource to determine the flow though the FSM in order to produce a response.
+
+As an example, imagine the following request:
+
+    $ curl  "http://example.org/widgets/1" -H "Accept: application/json" -u jsmith -p secret
+
+The series of "facts" that Webmachine will determine as it moves through the state machine for this request include:
+
+  * Does the route /widgets/:id exist?
+  * Does a widget with ID 1 exist?
+  * Is jsmith with the given password allowed to execute this HTTP method on this widget?
+  * Can the GET method be called for a widget?
+  * Can a widget be rendered as application/json?
+
+If the answer to each of these questions is "yes", then Webmachine will ask the final question - please render the response for me. If the answer to any of the questions along the way is "no", then the appropriate HTTP response code will be returned automatically.
+
+## Creating a resource
+
+* The way you tell Webmachine the facts about your resource is to create a class that extends Webmachine::Resource, and override the relevant callbacks. For example, what content types it provides (`content_types_accepted`), what HTTP methods it supports (`allowed_methods`), whether or not it exists (`resource_exists?`), and how the resource should be rendered (`to_json`). See the [examples][examples] page for examples of how to implement support for each HTTP method.
+
+```ruby
+class WidgetResource < Webmachine::Resource
+
+  def allowed_methods
+    ["GET"]
+  end
+
+  def content_types_provided
+    [["application/json", :to_json]]
+  end
+
+  def resource_exists?
+    widget # Truthy or falsey
+  end
+
+  def to_json
+    widget.to_json
+  end
+
+  private
+
+  def widget
+    @widget ||= Widget.find(id)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+
+end
+```
+
+* To see a list of the callbacks that can be overridden, and documentation about how to override each one, check out the [Callbacks][callbacks] class.
+
+* Callbacks that have a name with a question mark should return a truthy or falsey value, or an integer response code.
+
+* Most callbacks can interrupt the decision flow by returning an integer response code. You generally only want to do this when new information comes to light, requiring a modification of the response.
+
+* Once an "end state" has been reached (for example, `resource_exists?` returns falsey to a GET request, or a callback returns an explicit response code), the FSM will stop the decision flow, and return the relevant response code to the client. The implication of this is that callbacks later in the flow (eg. the method to render the resource) can rely upon the fact that the resource's existence has already been proven, that authorisation has already been checked etc. so there is no need for any `if object == nil` type boilerplate.
+
+### Advanced
+
+* Once you've seen how to implement a resource, the best way to get an understanding of how the FSM uses that resource is to check out the [Decision Flow Diagram][diagram] and then see how it is implemented in the [Flow][flow] class.
+
+### Guidelines
+
+* A collection resource (eg. /orders) should be implemented as a separate class to a single object resource (eg. /orders/1), as the routes represent different underlying objects with different "facts". For example, the orders _collection_ resource probably always exists (but may be empty), however the order with ID 1 may or may not exist.
+
+[callbacks]: https://github.com/seancribbs/webmachine-ruby/blob/master/lib/webmachine/resource/callbacks.rb
+[diagram]: http://webmachine.basho.com/images/http-headers-status-v3.png
+[flow]: https://github.com/seancribbs/webmachine-ruby/blob/master/lib/webmachine/decision/flow.rb
+[examples]: /documentation/examples.md

data/documentation/routes.md

@@ -0,0 +1,97 @@
+# Routes
+
+## Paths
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    # Will map to /orders
+    add ["orders"], OrdersResource
+
+    # Will map to /orders/:id
+    # request.path_info[:id] will contain the matched token value
+    add ["orders", :id], OrderResource
+
+    # Will map to /person/:person_id/orders/:order_id and
+    # provide :person_id and :order_id in request.path_info
+    add ["person", :person_id, "orders", :order_id], OrderResource
+
+    # Will map to any path starting with /orders,
+    # but will not provide any path_info
+    add ["orders", :*], OrderResource
+
+    # will map to any path
+    add [:*], DefaultResource
+  end
+end
+```
+
+## Guards
+
+Guards prevent a request being sent to a Resource with a matching route unless its conditions are met.
+
+##### Lambda
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], lambda { |request| request.headers['X-My-App-Version'] == "1" }, OrdersResourceV1
+    add ["orders"], lambda { |request| request.headers['X-My-App-Version'] == "2" }, OrdersResourceV2
+  end
+end
+
+```
+
+##### Block
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], OrdersResourceV1 do | request |
+      request.headers['X-My-App-Version'] == "1"
+    end
+  end
+end
+
+```
+
+##### Callable class
+
+```ruby
+class VersionGuard
+
+  def initialize version
+    @version = version
+  end
+
+  def call(request)
+    request.headers['X-My-App-Version'] == @version
+  end
+
+end
+
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], VersionGuard.new("1"), OrdersResourceV1
+    add ["orders"], VersionGuard.new("2"), OrdersResourceV2
+  end
+end
+
+```
+
+## User defined bindings
+
+User defined bindings specified for a route will be made available through `request.path_info`.
+
+```ruby
+
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], OrdersResource, :foo => "bar"
+  end
+end
+
+request.path_info[:foo]
+=> "bar"
+
+```

data/documentation/validation.md

@@ -0,0 +1,159 @@
+# Validation
+
+There are a couple of callbacks that are the most appropriate for doing validation in. The first is the `malformed_request?` which runs early in the Finite State Machine, and the second is inside the content type handler, for example `from_json`.
+
+## malformed_request
+
+If `malformed_request?` returns a truthy value, then a 400 Bad Request will be returned. Unfortunately, at this early stage in the flow, we don't know what the `method` or the `Content-Type` are without inspecting the request, and this leads to some very Iffy code.
+
+```ruby
+class OrdersResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST", "GET"]
+  end
+
+  # Iffy! What method? GET doesn't require any validation.
+  def malformed_request?
+    if request.post?
+      # What Content-Type? Very Iffy!
+      if request.headers['Content-Type'] == "application/json"
+        ....
+      end
+    else
+      false
+    end
+  end
+
+  def content_types_accepted
+    [
+      ["application/json", :from_json],
+      ["application/xml", :from_xml]
+    ]
+  end
+
+  def content_types_provided
+    [
+      ["application/json", :to_json],
+      ["application/xml", :to_xml]
+    ]
+  end
+
+  def post_is_create?
+    true
+  end
+
+  def create_path
+    "/orders/#{next_id}"
+  end
+
+  def from_json
+    order = Order.from_json(request.body.to_s)
+    response.body = order.save(next_id).to_json
+  end
+
+  def from_xml
+    order = Order.from_xml(request.body.to_s)
+    response.body = order.save(next_id).to_xml
+  end
+
+  def to_json
+    Order.all.to_json
+  end
+
+  def to_xml
+    Order.all.to_xml
+  end
+
+  private
+
+  def next_id
+    @next_id ||= Order.next_id
+  end
+
+end
+```
+
+## Content-Type handler
+
+A more elegant way to handle validation is to do it in a callback where we already know the `method` and the `Content-Type` - that is, the handler for the given Content-Type (eg. `from_json` and `from_xml`). By returning a `400` from the handler, we stop the state machine flow.
+
+```ruby
+class OrdersResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST", "GET"]
+  end
+
+  # Iffy! What method? GET doesn't require any validation.
+  def malformed_request?
+    if request.post?
+      invalid_create_order_request?
+    else
+      false
+    end
+  end
+
+  def content_types_accepted
+    [
+      ["application/json", :from_json],
+      ["application/xml", :from_xml]
+    ]
+  end
+
+  def content_types_provided
+    [
+      ["application/json", :to_json],
+      ["application/xml", :to_xml]
+    ]
+  end
+
+  def post_is_create?
+    true
+  end
+
+  def create_path
+    "/orders/#{next_id}"
+  end
+
+  def from_json
+    order = Order.from_json(request.body.to_s)
+    # A bit less Iffy!
+    return json_validation_errors(order) unless order.valid?
+    response.body = order.save(next_id).to_json
+  end
+
+  # This could use some DRYing up, but you get the point.
+  def from_xml
+    order = Order.from_xml(request.body.to_s)
+    # A bit less Iffy!
+    return xml_validation_errors(order) unless order.valid?
+    response.body = order.save(next_id).to_xml
+  end
+
+  def to_json
+    Order.all.to_json
+  end
+
+  def to_xml
+    Order.all.to_xml
+  end
+
+  private
+
+  def json_validation_errors(order)
+    response.body = order.validation_errors.to_json
+    400
+  end
+
+  def xml_validation_errors(order)
+    response.body = order.validation_errors.to_xml
+    400
+  end
+
+  def next_id
+    @next_id ||= Order.next_id
+  end
+
+end
+```