REST Toolkit 1.0 documentation

Philosophy

«  Security   ::   Contents   ::   API documentation  »

Philosophy

rest_toolkit tries to follow the standard REST standards for HTTP as much as possible:

A resource typically corresponds to something stored in a database. The mapping does not need to be one-to-one: stored data can be exposed at multiple places by an API, and each location is a separate resource from a REST point of view. For example in an event management system a user can see see event information in a list of events he has registered for as /users/12/events/13, while an event staff member manages the event via a /events/13. Both URLs will use the same event object in the database, but are separate REST resources, and will return different data, use a different ACL, etc.

rest_toolkit follows this philosophy ant matches URLs to resources instead of stored data. This has several advantages:

Request flow

When processing a request pyramid will go through several steps.

Visual overview of the request flow.

  1. When a request comes in the first step is to find a resource class which matches the requested URL.
  2. The constructor for the resource class found in step 1 is called to create the resource instance. The constructor can raise an exception at this step to indicate no resource data could be found, for example if an requested id can not be found in a database.
  3. Try to find a view for the resource and request type. This can either be a default view or a view defined via an request method decorator. If no view is found a HTTP 405 Method Not Allowed error is returned.
  4. The view is invoked. The data it returns will be converted to JSON and returned to the client.

«  Security   ::   Contents   ::   API documentation  »