cleaREST 0.3.5

URL Routing

is done by decorating your handling function with one of these decorators:

• @GET

• @POST

only one argument is required (url to handle) ie:

@GET("/my/awesome/url")
def my_function():
    ...

optionally you can specify successful http result status (default is HTTP_OK) ie:

@GET("/my/awesome/url", status=HTTP_CREATED)
def my_function():
    ...

list of status tuples:

• HTTP_OK

• HTTP_CREATED

Variables

• GET variables from query string

• POST variables can be send as:

• application/x-www-form-urlencoded

• multipart/form-data

• application/json

• url path variables (identifier inside curly brackets) ie:

  @GET("/my/awesome/url/{variable}")
  def my_function(variable):
      ...

Parsing

per parameter parsing function assigned as default value ie:

@GET("/my/awesome/url")
def my_function(myid=int):
    ...

optional parameter:

@GET("/my/awesome/url")
def my_function(myid=(int, 0)):
    ...

reduction multiple into one:

@GET("/my/awesome/url")
def my_function(user_id=lambda user, password: login):
    ...

Returning data

build-in support:

you can also register any custom data-type or override table above with:

register_content_type(type_, content_type, handler)

Errors

to return a http error raise one of these exceptions:

• HttpBadRequest

• HttpNotFound

• HttpUnsupportedMediaType

• HttpNotImplemented

ie:

@GET("/my/awesome/url")
def my_function(myid=int):
    if myid == -1:
         raise HttpNotFound()
    ...

HTML Documentation

when is url opened by web-browser html documentation is shown instead of actual function call.

• “application/xhtml+xml” in accept http header

• similar tags to sphinx/docutils

• extra example tags: “:example:” and for response “:rexample”:

ie:

@GET("/my/api")
def my_function(a, b=int):
    """
    Describe your function here.

    :param str a: Describe a here.
    :param int b: Describe b here.
    :return: W/E you function returns.

    :example::

        GET /my/api?a=someting&b=42

    :rexample::

        {
            "something": "something"
            ...
        }
    """
    ...

“real app” example: