Commits

Anonymous committed c83cbf3

reftrans, upgrade, and better home

  • Participants
  • Parent commits ae65aaf

Comments (0)

Files changed (3)

-== Welcome to Webmachine! ==
-
-Webmachine is not very much like the Web frameworks you're used to.
-
-Webmachine gives you a place to define the representations and other Web-relevant properties of your application's resources -- with the emphasis that the first-class things on the Web are resources and that their essential properties of interaction are already quite well defined and usefully constrained.
-
-You can call Webmachine a REST toolkit if you like, and I won't argue with you.  However, even that doesn't tell you what exactly it does.
-
-It is an application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management provided by mochiweb.
-
-A Web application in Webmachine is a set of resources, and resources are defined by functions or predicates over their state. That might sound abstract or confusing, but it turns out to be quite simple to implement. I've provided some trivial examples to show just how simple it is.
-
-The very first implementation of Webmachine was inspired in large part by version 1 of Alan Dean's HTTP flow diagram. I subsequently worked with Alan to improve the diagram as we developed Webmachine. Webmachine's request handling engine reflects the result of that collaboration explicitly.
-
-A little bit of prose can be found at http://blog.therestfulway.com/
-
-insert links in all above pargraphs, and link to all of:
-
-[[QuickStart]]
-[[WebmachineResources]]
-[[ReftransUpgrade]]
-[[ExampleResources]]
-[[WebmachineSetup]] 
-[[DispatchConfiguration]]
-[[WebmachineHowto]]
-[[BigHTTPGraph]]
-[[WebmachineReqData]]
-
-
-
+== Welcome to Webmachine! ==
+
+Webmachine is not very much like the Web frameworks you're used to.
+
+You can call Webmachine a REST toolkit if you like, and I won't argue with you.
+
+It is an application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management provided by mochiweb, and provides a simple and clean way to connect that to your application's behavior.
+
+A Webmachine application is a set of resources, each of which is a set of functions over the state of the resource.  We really mean functions here, not object-methods, infinite-server-loops, or any other such construction.  This aspect of Webmachine is one of the reasons why Webmachine applications are relatively easy to understand and extend.
+
+These functions give you a place to define the representations and other Web-relevant properties of your application's resources -- with the emphasis that the first-class things on the Web are resources and that their essential properties of interaction are already quite well defined and usefully constrained.
+
+For most Webmachine applications, most of the functions are quite small and isolated.  One of the nice effects of this is that a quick reading of a resource will give you an understanding of the application, its Web behavior, and the relationship between them.  Since these functions are usually [[WebmachineReftrans|functions|referentially transparent]], Webmachine applications can be quite easy to test.  There's no need for mock objects, fake database connections, or any other wastes of time when you can write tests against each component of your application in terms of the input and output to various functions.
+
+From here, you can:
+* [[ExampleResources|read some examples]]
+* [[QuickStart|get started right away]]
+* [[WebmachineMechanics|understand Webmachine's execution model]]
+* [[DispatchConfiguration|configure your URL dispatching]]
+* [[WebmachineResources|learn about the functions that can make up a resource]]
+* [[WebmachineReqData|see how your resource can access the HTTP Request]]
+* [[WebmachineUpgrade|upgrade your application from an old version of Webmachine]]
+* [[WebmachineDebugging|debug your application]]
+
+In addition to this documentation, occasionally something is written about Webmachine at http://blog.therestfulway.com/
+
+
+
+
+
+

File WebmachineReftrans.wiki

+== Webmachine's approach to resource functions and referential transparency ==
+
+Webmachine goes to great lengths to help your [[WebmachineResources|resource functions]] to be as referentially transparent as possible.  By "referentially transparent" we mean that given the same input {{{ {ReqData, Context} }}} the function will return the same output {{{ {Result, ReqData, Context} }}} and that side effects will be insignificant from the point of view of Webmachine's execution.
+
+We don't try to force you into pure referential transparency; we give you as big a hole as you want via {{{ Context.}}}  As that term is application-specific, you can put database handles, server process identifiers, or anything else you like in there and we won't try to stop you.
+
+However, all Webmachine really cares about is the rest of the terms.  Since resource functions are generally referentially transparent at least with regard to those terms, many things are easier -- testing, [[WebmachineDebugging|debugging]], and even static analysis and reasoning about your Web application.
+

File WebmachineUpgrade.wiki

+== Upgrading your application from versions of Webmachine < 1.0 ==
+
+Prior to the 1.0 release of Webmachine, resource functions had a different signature.  They went from this:
+
+{{{
+#!erlang
+f(ReqProps, Context) -> {Result, Context}
+}}}
+
+to this:
+
+{{{
+#!erlang
+f(ReqData, Context) -> {Result, ReqData, Context}
+}}}
+
+The main difference here is that {{{ReqProps}}} had a handle to a {{{gen_server}}} commonly referred to as {{{Req}}} which was the interface to the request/response data for the resource.  
+
+That was reasonably convenient but it meant that many changes to the response occurred by side effect, and also that it was hard to statically determine what elements of the request were needed for a given resource function to perform.  These facts made testing less comfortable than we wanted, so we decided it was worth breaking backward compatibility in order to get [[WebmachineReftrans|much greater testability via referential transparency]].
+
+Everywhere that an old Webmachine resource used to call a function from the parameterized module returned by {{{?REQ(ReqProps)}}} it can now instead access or produce a {{{ReqData}}} structure using the [[WebmachineReqData|wrq module]].
+
+A few examples, assuming {{{Req = ?REQ(ReqProps)}}}:
+
+|=Old|=New|
+|{{{Req:get_header_value("content-type")}}}|{{{wrq:get_req_header("content-type", ReqData)}}}|
+|{{{Req:recv_body()}}}|{{{wrq:req_body(ReqData)}}}|
+|{{{?PATH(ReqProps)}}}|{{{wrq:disp_path(ReqData)}}}|
+|{{{Req:add_response_header("X-Foo", "foo!")}}}|{{{wrq:set_resp_header("X-Foo", "foo!", ReqData)}}}|
+
+Note a subtle and important detail about the last of those examples: While the old method actually did the modification for you by side effect, the new way simply returns a new {{{ReqData}}} structure.  For this changed structure to have an effect, you must return it in the {{{ReqData}}} portion of your resource function's return tuple.
+