Your First Application

Directory Structure

Watson has a preferred directory structure for it’s applications which can be created automatically by the project new [project name] [app name] command.



For example project new sample creates a new project named and an application package named sample

The application will be created within the current working directory, unless you override it with the -d DIR option.

Once the structure has been created, you can use ./ to perform related console commands from within the application, for example: ./ project routes to display a list of routes for the application.


By creating your project using the project new command Watson will generate 3 configuration files for your application as well as a route file.

  4. is the basic configuration to get your application up and running locally and is identical to By default will enable profiling and debugging of the application. If you have retrieved the application from a VCS then you would make a copy of with the name and modify the settings within there.


from project.config.routes import routes

debug = {
    'enabled': True,

When deploying to a production environment you would make a copy of and name it to load the relevant production settings.

The dist files are designed to maintain a consistent configuration when an application is being worked on by multiple developers. We recommend adding [app_name]/config/ to your .gitignore file to prevent your personal configuration from being used by another developer. contains all the routes associated with the application. For more detail on how to define routes, please see the MVC Key Concept area.


routes = {
    'index': {
        'path': '/',
        'defaults': {'controller': 'project.controllers.Index'}

Putting it all together

Most likely you’ll want to develop locally first and then deploy to a production environment later. Watson comes packaged with a command to run a local development server which will automatically reload when changes are saved. To run the server simply change to the project directory and run ./ dev runserver and then visit in your favorite browser where you’ll be greeted with a page saying welcome to Watson.

A initial controller is created for you in app_name/controllers/ which will response to a request for / in your browser (from the above definition)


from watson.framework import controllers, __version__

class Index(controllers.Rest):
    def GET(self):
        return 'Welcome to Watson v{0}!'.format(__version__)

Being a Rest controller any request will be routed to the instance method matching the HTTP_REQUEST_METHOD environ variable from the associated request. One of the benefits of using a Rest controller is that you no longer need to check the request method to determine how you should respond.

An alternative would be to use an Action controller instead. This would be represented in the following way:

from watson.framework import controllers, __version__

class Index(controllers.Action):
    def index_action(self):
        return 'Welcome to Watson v{0}!'.format(__version__)

All Action controller methods are suffixed with _action. For a more indepth look at what functions a controller can perform, check out the common_usage area for controllers. For a general overview of how controllers are used within Watson, check out the MVC Key Concept area.

The presentation layer (or view) is matched based on lowercased versions of the the class name and action of the controller. For the above request the following view is rendered:


<!DOCTYPE html>
        <title>Welcome to Watson!</title>
        <h1>{{ content }}</h1>
        <p>You are now on your way to creating your first application using Watson.</p>
        <p>Read more about Watson in <a href="">the documentation.</a>

For more information on views, check out the MVC Key Concept area.

You will also want to make sure that you unit test your application, and you can do that by running ./ project test. A simple unit test is already included when the project new command is run. It is designed to fail so make sure you go in and make the required changes for it to pass!

All tests are located under the tests directory. For example the demo unit test is located at tests/[app name]/controllers/

Watson supports both nose and py.test for use with the project test command and one of these is required to run application test suites.