120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
A Restful front controller built on Hack.
|
|
|
|
Below is an overview of how the refactored code will hopefully turn out.
|
|
|
|
# Terminology
|
|
|
|
## Verb
|
|
|
|
HTTP request methods. Possible values: GET, POST, PUT, DELETE. Please see
|
|
http://rest.blueoxen.net/cgi-bin/wiki.pl?MinimumMethods. In sum:
|
|
|
|
GET: Read only.
|
|
PUT: Replace data on server.
|
|
DELETE: Remove data from server.
|
|
POST: Some form of update.
|
|
|
|
Note: not all clients support PUT and DELETE. Therefore, we need a
|
|
workaround. There are two fixes:
|
|
|
|
1. X-HTTP-Method-Override header.
|
|
2. Get parameter _method_override (ie, in the query string). This will be more
|
|
useful for web forms.
|
|
|
|
See MethodOverride middleware.
|
|
|
|
## Resource
|
|
|
|
A Resource is a single URL. Each Resource can be addressed with the four verbs,
|
|
though does not necesarily support all of them. There are a few different ways
|
|
of passing parameters:
|
|
|
|
1. URL parameter. For example, you can set up your application so that
|
|
/articles/my_title/ will hand off to the article resource with a parameter of
|
|
my_title. The idea here is to avoid the regexs present in most other
|
|
frameworks and provide a uniform interface for all parameters.
|
|
|
|
2. Get parameter, ie query string.
|
|
|
|
3. Post parameter, ie content body. This is *not* available for GET requests.
|
|
However, it *is* available for PUT and DELETE.
|
|
|
|
4. Headers, including cookies.
|
|
|
|
### ResourceName
|
|
|
|
As a side point to the URL parameter mentioned above: let us say you have
|
|
multiple resources like /articles/my_title/ and /articles/other_title/. You
|
|
clearly do not want to write code twice to process these requests. Instead,
|
|
convert the article name into a URL parameter and then articles will have its
|
|
own ResourceName.
|
|
|
|
NOTE: This has taken on a very central role in the restful library, in addition
|
|
to the RestfulApp class. Hopefully I will have a chance to document this soon.
|
|
As a result, some of the following documentation is outdated.
|
|
|
|
### ResourceParser
|
|
|
|
A ResourceParser converts a Resource (ie, a URL) to a ResourceName and URL
|
|
parameters.
|
|
|
|
## RawRequest
|
|
|
|
The parsed data sent from the client. Has, for example, GET and POST
|
|
parameters, not QUERY_STRING and CONTENT_BODY.
|
|
|
|
## Request
|
|
|
|
Request is actually a **type class** for parsing a RawRequest. This allows
|
|
putting all form handling code and the like into a single place. Your handler
|
|
code (see below) need only deal with your data type.
|
|
|
|
## Representation
|
|
|
|
Some method of showing data to the client. These are identified by MIME types.
|
|
For the most part, you should be using hierarchichal data (see Data.Object).
|
|
There are some exceptions, such as:
|
|
|
|
* HTML for non-Ajax clients (search engines, old browsers).
|
|
* Atom/RSS feeds.
|
|
* Sitemaps.
|
|
|
|
Whenever possible, use Data.Object, as this will automatically handle some
|
|
basic representations (JSON, JSONP, Yaml, XML, undecorated HTML).
|
|
|
|
## Response
|
|
|
|
Contains basic HTTP response information and something which can be represented
|
|
in different ways.
|
|
|
|
## Handler
|
|
|
|
There is a single Handler for each combination of ResourceName and Verb. A
|
|
Handler takes some instance of Request and returns a Response.
|
|
|
|
### HandlerMap
|
|
|
|
Maps a ResourceName/Verb pair to a Handler.
|
|
|
|
## Application
|
|
|
|
An application is essentially a ResourceParser and HandlerMap. It also has some
|
|
settings involved.
|
|
|
|
# Static files
|
|
|
|
All static files should go under the /static/ path. A typical application will
|
|
probably have a Javascript file in there which deals directly with the entire
|
|
Restful API.
|
|
|
|
# Non-Ajax clients
|
|
|
|
Search engines nad older clients should not be ignored. However, it is quite
|
|
tedious to write view code twice. Hopefully, in the future there will be a view
|
|
component to this framework which can automate some of that process.
|
|
|
|
# Passing global data
|
|
|
|
You should use function currying to pass around global information (the list of
|
|
entries in a blog, a database connection, etc).
|