rest_toolkit tries to follow the standard REST standards for HTTP as much as possible:
- every URL uniquely identifies a resource
- an OPTIONS request must return the list of supported request methods in an Access-Control-Allow-Methods header.
- a request using an unsupported request method must return a HTTP 405 error.
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:
- your data model does not need to be aware of frontend-specific things like access control lists or JSON formatting.
- you can easily present the same data in multiple ways.
When processing a request pyramid will go through several steps.
- When a request comes in the first step is to find a resource class which matches the requested URL.
- 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.
- 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.
- The view is invoked. The data it returns will be converted to JSON and returned to the client.