Tutorial: creating an API endpoint¶

Basic resource¶

We’ll create an /example/ endpoint, used to manipulate fruits. We’ll create an Example resource, supporting GET and POST HTTP methods. First of all, we’ll create a class with get and post methods in cloudkitty/api/v2/example/example.py:

import flask_restful


class Example(flask_restful.Resource):

    def get(self):
        pass

    def post(self):
        pass

Validating a method’s parameters and output¶

A GET request on our resource will simply return {“message”: “This is an example endpoint”}. The add_output_schema decorator adds voluptuous validation to a method’s output. This allows to set defaults.

cloudkitty.api.v2.utils.add_output_schema(schema)[source]¶

Add a voluptuous schema validation on a method’s output

Example usage:

class Example(flask_restful.Resource):

    @api_utils.add_output_schema({
        voluptuous.Required(
            'message',
            default='This is an example endpoint',
        ): api_utils.get_string_type(),
    })
    def get(self):
        return {}

Parameters:	schema (dict) – Schema to apply to the method’s output

Let’s update our get method in order to use this decorator:

import flask_restful
import voluptuous

from cloudkitty.api.v2 import utils as api_utils


class Example(flask_restful.Resource):

    @api_utils.add_output_schema({
        voluptuous.Required(
            'message',
            default='This is an example endpoint',
        ): api_utils.get_string_type(),
    })
    def get(self):
        return {}

$ curl 'http://cloudkitty-api:8889/v2/example'
{"message": "This is an example endpoint"}

It is now time to implement the post method. This function will take a parameter. In order to validate it, we’ll use the add_input_schema decorator:

cloudkitty.api.v2.utils.add_input_schema(location, schema)[source]¶

Add a voluptuous schema validation on a method’s input

Takes a dict which can be converted to a volptuous schema as parameter, and validates the parameters with this schema. The “location” parameter is used to specify the parameters’ location. Note that for query parameters, a MultiDict is returned by Flask. Thus, each dict key will contain a list. In order to ease interaction with unique query parameters, the SingleQueryParam voluptuous validator can be used:

from cloudkitty.api.v2 import utils as api_utils
@api_utils.add_input_schema('query', {
    voluptuous.Required('fruit'): api_utils.SingleQueryParam(str),
})
def put(self, fruit=None):
    return fruit

To accept a list of query parameters, the following syntax can be used:

from cloudkitty.api.v2 import utils as api_utils
@api_utils.add_input_schema('query', {
    voluptuous.Required('fruit'): [str],
})
def put(self, fruit=[]):
    for f in fruit:
        # Do something with the fruit

Parameters:	location (str) – Location of the args. Must be one of [‘body’, ‘query’] schema (dict) – Schema to apply to the method’s kwargs

Arguments validated by the input schema are passed as named arguments to the decorated function. Let’s implement the post method. We’ll use Werkzeug exceptions for HTTP return codes.

@api_utils.add_input_schema('body', {
    voluptuous.Required('fruit'): api_utils.get_string_type(),
})
def post(self, fruit=None):
    policy.authorize(flask.request.context, 'example:submit_fruit', {})
    if not fruit:
        raise http_exceptions.BadRequest(
            'You must submit a fruit',
        )
    if fruit not in ['banana', 'strawberry']:
        raise http_exceptions.Forbidden(
            'You submitted a forbidden fruit',
        )
    return {
        'message': 'Your fruit is a ' + fruit,
    }

Here, fruit is expected to be found in the request body:

$ curl -X POST -H 'Content-Type: application/json' 'http://cloudkitty-api:8889/v2/example' -d '{"fruit": "banana"}'
{"message": "Your fruit is a banana"}

In order to retrieve fruit from the query, the function should have been decorated like this:

@api_utils.add_input_schema('query', {
    voluptuous.Required('fruit'): api_utils.SingleQueryParam(str),
})
def post(self, fruit=None):

Note that a SingleQueryParam is used here: given that query parameters can be specified several times (eg xxx?groupby=a&groupby=b), Flask provides query parameters as lists. The SingleQueryParam helper checks that a parameter is provided only once, and returns it.

class cloudkitty.api.v2.utils.SingleQueryParam(param_type)[source]¶

Voluptuous validator allowing to validate unique query parameters.

This validator checks that a URL query parameter is provided only once, verifies its type and returns it directly, instead of returning a list containing a single element.

Note that this validator uses voluptuous.Coerce internally and thus should not be used together with api_utils.get_string_type in python2.

Parameters:	param_type – Type of the query parameter

Authorising methods¶

The Example resource is still missing some authorisations. We’ll create a policy per method, configurable via the policy.yaml file. Create a cloudkitty/common/policies/v2/example.py file with the following content:

from oslo_policy import policy

from cloudkitty.common.policies import base

example_policies = [
    policy.DocumentedRuleDefault(
        name='example:get_example',
        check_str=base.UNPROTECTED,
        description='Get an example message',
        operations=[{'path': '/v2/example',
                     'method': 'GET'}]),
    policy.DocumentedRuleDefault(
        name='example:submit_fruit',
        check_str=base.UNPROTECTED,
        description='Submit a fruit',
        operations=[{'path': '/v2/example',
                     'method': 'POST'}]),
]


def list_rules():
    return example_policies

Add the following lines to cloudkitty/common/policies/__init__.py:

# [...]
from cloudkitty.common.policies.v2 import example as v2_example


def list_rules():
    return itertools.chain(
        base.list_rules(),
        # [...]
        v2_example.list_rules(),
    )

This registers two documented policies, get_example and submit_fruit. They are unprotected by default, which means that everybody can access them. However, they can be overriden in policy.yaml. Call them the following way:

# [...]
import flask

from cloudkitty.common import policy


class Example(flask_restful.Resource):
    # [...]
    def get(self):
        policy.authorize(flask.request.context, 'example:get_example', {})
        return {}

    # [...]
    def post(self):
        policy.authorize(flask.request.context, 'example:submit_fruit', {})
        # [...]