HTTP Routing utilities

The pelix.http.routing module provides a utility class and a set of decorators to ease the development of REST-like servlets.

Decorators

Important

A servlet which uses the utility decorators must inherit from the pelix.http.routing.RestDispatcher class.

The pelix.http.routing.RestDispatcher class handles all do_* methods and calls the corresponding decorated methods in the child class.

The child class can declare as many methods as necessary, with any name (public, protected or private) and decorate them with the following decorators. Note that a method can be decorated multiple times.

class pelix.http.routing.Http(route, methods=None)

Decorator indicating which route a method handles

Parameters:
  • route – Path handled by the method (beginning with a ‘/’)
  • methods – List of HTTP methods allowed (GET, POST, ...)
class pelix.http.routing.HttpGet(route)

Bases: pelix.http.routing.Http

Decorates a method handling GET requests

Parameters:route – Path handled by the method (beginning with a ‘/’)
class pelix.http.routing.HttpPost(route)

Bases: pelix.http.routing.Http

Decorates a method handling POST requests

Parameters:route – Path handled by the method (beginning with a ‘/’)
class pelix.http.routing.HttpPut(route)

Bases: pelix.http.routing.Http

Decorates a method handling PUT requests

Parameters:route – Path handled by the method (beginning with a ‘/’)
class pelix.http.routing.HttpHead(route)

Bases: pelix.http.routing.Http

Decorates a method handling HEAD requests

Parameters:route – Path handled by the method (beginning with a ‘/’)
class pelix.http.routing.HttpDelete(route)

Bases: pelix.http.routing.Http

Decorates a method handling DELETE requests

Parameters:route – Path handled by the method (beginning with a ‘/’)

The decorated methods muse have the following signature:

decorated_method(request, response, **kwargs)

Called by the dispatcher to handle a request.

The keyword arguments must have the same name as the ones given in the URL pattern in the decorators.

Parameters:

Supported types

Each argument in the URL can be automatically converted to the requested type. If the conversion fails, an error 500 is automatically sent back to the client.

Type Description
string Simple string used as is. The string can’t contain a slash (/)
int The argument is converted to an integer. The input must be of base 10. Floats are rejected.
float The argument is converted to a float. The input must be of base 10.
path A string representing a path, containing slashes.
uuid The argument is converted to a uuid.UUID class.

Multiple arguments can be given at a time, but can only be of one type.

Sample

from pelix.ipopo.decorators import ComponentFactory, Provides, Property, \
   Instantiate
from pelix.http import HTTP_SERVLET, HTTP_SERVLET_PATH
from pelix.http.routing import RestDispatcher, HttpGet, HttpPost

@ComponentFactory()
@Provides(HTTP_SERVLET)
@Property('_path', HTTP_SERVLET_PATH, '/api/v0')
@Instantiate("some-servlet")
class SomeServlet(RestDispatcher):
   @HttpGet("/list")
   def list_elements(self, request, response):
      response.send_content(200, "<p>The list</p>")

   @HttpPost("/form/<form_id:uuid>")
   def handle_form(self, request, response, form_id):
      reponse.send_content(200, "<p>Handled {}</p>".format(form_id))

   @HttpPut("/upload/<some_id:int>/<filename:path>")
   @HttpPut("/upload/<filename:path>")
   def handle_upload(
   self, request, response,
                     some_id=None, filename=None):
      reponse.send_content(200, "<p>Handled {} : {}</p>" \
         .format(some_id, filename))