Writing a Blueprint

All API functionality in RelengAPI is implemented in the form of Flask blueprints. These blueprints nicely isolate related functionality both in the codebase (relengapi/blueprints/foobar) and in the API (https://api.pub.build.mozilla.org/foobar).

Starting a New Blueprint

Pick a name for your blueprint. This guide will use "bubbler", so it's easy to spot.

Create a new Python package under relengapi/blueprints, with static and templates directories for assets.

mkdir -p relengapi/blueprints/bubbler/{static,templates}
touch relengapi/blueprints/bubbler/__init__.py

Within __init__.py, create a new blueprint:

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

import structlog

from flask import Blueprint
from relengapi.lib.api import apimethod

logger = structlog.get_logger()
bp = Blueprint('bubbler', __name__,
            static_folder='static',
            template_folder='templates')

And create an API endpoint:

@bp.route('/bubble')
@apimethod([unicode])
def bubble():
    """Release a volume of gas into a liquid"""
    return u"bloop!"

Create a test script, relengapi/blueprints/bubbler/test_bubbler.py:

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

from flask import json
from nose.tools import eq_
from relengapi.lib.testing.context import TestContext

test_context = TestContext()

@test_context
def test_bubble(client):
    """Getting /bubbler/bubble should return 'bloop!'"""
    resp = client.get('/bubbler/bubble')
    eq_(json.loads(resp.data)['result'], u"bloop!")

Finally, attach your blueprint to the rest of relengapi by adding it to the list of blueprints in relengapi/app.py:

blueprints = [_load_bp(n) for n in [
    ..
    "bubbler",
    ..
]]

You can now run the unit tests with

relengapi run-tests

And you can perform the same validation that Travis will with

bash validate.sh

Get hacking!