This documentation is about how to create a REST like API Service by using the two decorators RestService and rpcmethod.

Example Service

Here is one simple REST service to demonstrate how to use the decorators:

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from .rest import RestService, rpcmethod_route

@RestService('hello')                                                  # (1)
class HelloService(object):

    def __init__(self, request):                                       # (2)
        self.request = request

    @rpcmethod_route(route_suffix='/{name}', request_method='POST')    # (3)
    def sample(self, name, data):                                      # (4)
        return dict(name=name, keys=len(data.keys()))


if __name__ == '__main__':
    config = Configurator()
    config.add_route('hello', '/hello', static=True)                   # (5)
    config.commit()                                                    # (6)
    config.scan()

    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

Once the service has been started issue a request with curl like this:

$ curl -XPOST -H "Content-Type: application/json" localhost:8080/hello/you \
  -d '{"data":{"a":42, "b":"c"}}'
{"keys": 2, "name": "you"}

Step by step

Implementation

The first thing to setup a REST service is a class decorated with RestService (1). The required parameter given to the decorator indicates the base route name to which the service will be bound. The class to decorate has to accept a request parameter in the constructor because this class will be used as the view (2).

Second, one or more methods of this class has to be decorated with rpcmethod_route (3). If no parameters were passed to the rpcmethod_route decorator the endpoint for this method will be available at the pattern of the configured base route (in the example above it’s ‘/hello’) with the http method GET. The decorator also provides a parameter called route_suffix which get appended to the pattern of the base route (in the example above it’s ‘/{name}’). Any other given keyword arguments get passed to the internal add_route command. For details see the documentation of pyramids config.add_route method .

The decorated method has to have a proper signature to match the incoming request (4). The following keyword arguments will be passed to the method:

- the matchdict (in the example above {name} from the suffix pattern)
- request params
- request body

Configuration

We need to add the base route registered with the name used in the RestService decorator (5). Since this route is not relevant for url dispatching it make sence to register the route as a static route.

Note

It is neccesary to commit the config after registering the base routes and before calling config.scan() because otherwise the base route is not available while processing the decorator and so it’s not possible to determine the pattern of the base route (6).

The config.scan() step will process the decorator which add’s implicitly the route and the view for each decorated method.