Table Of Contents

Previous topic

Welcome to RedBarrel’s documentation!

Next topic

Installing RedBarrel

This Page

What’s RedBarrel ?

tldr; RedBarrel is a DSL and Micro-Framework to write Web Services

RedBarrel allows you to describe your Web Services via a Domain Specific Language (DSL) and organize your code in a very simple way. The DSL replaces the code usually needed to route you request to the right piece of code, and let you describe all the pre- and post- steps.

RedBarrel can be used to write any kind of web application, but is specifically designed to write Web Services.

Anatomy of a Web Service

A Web Service is basically doing these four steps:

  1. [pre-processing] Check the request body and headers, and potentially reject it. Rejection can be due to a Basic Authentication failure, an unexpected value for the request body, etc.
  2. [routing] Find what code or application should be called to build the response. This is usually computed with the path information and sometimes some headers.
  3. [execution] Invoke some code to build the response
  4. [post-processing] Return the response built and maybe do some post-processing or post-assertions like converting the content-type etc.

In Python, when you build web services using a WSGI framework like Pylons, Pyramid, or simply Routes + WebOb, all of these steps happen in your code. You define the routing using Routes descriptions, or using more clever dispatching systems like what Pyramid offers, then delegate the execution to a controller class or a simple function, after a potential pre-processing. Although the pre-processing part is often merged with the execution part because they are closely related.

For instance, if you have a web service that requires a JSON mapping in the request body, you could write something that looks like:

def my_webservice(request):
        data = json.loads(request.body)
    except ValueError:
        # this raises a 400
        raise HTTPBadRequest("Unknown format -- we want JSON")

    ... do something ...

Of course you can always generalize this by using a decorator to clearly separate the pre-processing part:

def my_webservice(request):
    ... do something ...

Same thing for the post-processing step:

def my_webservice(request):
    ... do something ...

And in some frameworks, the routing itself is expressed as a decorator:

def my_webservice(request):
    ... do something ...

It turns out that there are a lot of pre/post steps that can be pushed to a meta level.

With RedBarrel, Steps 1., 2. and 4. are described in a Domain Specific Language (DSL) instead of decorators or other meta-level code.


RedBarrel pushes all the pre- and post- processing descriptions in a DSL called RBR. The RBR file also describes in detail every web service, like the path to invoke them, which HTTP method should be used, what possible status codes will be returned, etc.

The first benefit is a natural separation of the code that actually does the job, from the code that checks or converts inputs and outputs. When you are developing a web service, you don’t have to worry anymore about checking the request or setting the response content-type. You can just focus on the feature. This separation favors code reuse and reduces the boiler-plate code of your application: all the post- and pre- conditions can be grouped in a library that’s reused accross all your web services.

A DSL also allows a possible delegation of pre/post tasks to a higher layer: if the RedBarrel DSL was to be implemented as an Nginx module all the pre- and post- processing could happen at the web server level, allowing an interesting leverage of resources. Rejecting bad request in NGinx makes more sense than doing it in the Python backend.

Last, expressing web services in a DSL facilitates introspection: the RedBarrel default implementation for instance, creates a HTML view of all available webservices.

Writing an application with RedBarrel

Writing a web application with RedBarrel consists of describing the logic of every web service in a RBR file, then worry about the implementation of every piece. There is no MVC paradigm or anything similar that the developer must follow. You can write your code in functions, classes or whatever, and just hook them into the RBR file.

For example, the RBR for a simple Hello world app can look like this:

path hello_world (
    description "Simplest application: Hello World!",
    method GET,
    url /,
    use python:somemodule.hello

With a function hello located in somemodule:

def hello(request):
    return 'Hello World'

Have a look at a full example: Full example: an URL shortener.

What do you get with RedBarrel ?

The current version includes:

  • a parser for the RBR DSL.
  • a RBR syntax checker.
  • a pure Python implementation of a WSGI Web Server that can be launched with a RBR file.
  • a documentation generator.
  • a wizard to quick-start a project

What I’d like to have in a future revision:

  • a NGinx Module implementation
  • an Apache implementation
  • more backends than Python, so web services can execute JS, Erlang, etc
  • contributors

How to contribute ?

If you like the idea, you can contribute to the project, by:

  • using RedBarrel in one of your project and providing feedback
  • contributing code and/or documentation
  • etc.

Contact me at