3.2.1.1   Microservice server overview¶

Let’s pretend that you have a service living at https://myservice.lsst.codes, which you want to turn into a microservice (that is, put an api.lsst.codes-conformant API wrapper around) using apikit. Your service uses the Bitly OAuth2 proxy to use GitHub as its authentication source, so you need to leverage that.

We’ll say that this is going to go in a directory uservice_mymicroservice, and we will package it for installation via setuptools. The server itself will, imaginatively, be called server.py. (This mirrors the setup you would get if you used cookiecutter to create the service.)

3.2.1.2   Imports¶

We’ll cheat a little and start with all the imports we’re going to need; in real development, of course, you wouldn’t know this a priori but would build it up a bit at a time:

 from flask import jsonify, request
 from apikit import APIFlask, BackendError
 from BitlyOAuth2ProxySession import Session

3.2.1.3   Flask application¶

Having done that, we need to create the microservice as an instance of apikit.APIFlask. This class takes the same arguments as the object returned by metadata, with the following exception: auth becomes an object with two fields, type and data, unless auth is one of None, the empty string, or the string none. The type field must be one of the strings none, basic, or bitly-proxy.

If auth is an object whose type field is none, auth.data is the empty object, or omitted completely. Otherwise auth.data is an object with two fields, username and password. If auth.type is bitly-proxy then auth.data must have a third field, endpoint, which is the start point of the OAuth2 proxy data flow for the underlying service. Usually this is https://service.host/oauth2/start.

The api_version field has a sane default (currently 1.0) and can normally be omitted.

Here’s what all that looks like:

 backenduri = "https://myservice.lsst.codes"
 app = APIFlask(name="uservice-mymicroservice",
                version="0.0.1",
                repository="https://github.com/sqre-lsst/" +
                    "uservice-mymicroservice",
                description="My delightful microservice",
                route=["/", "/mymicroservice"],
                auth={"type": "bitly-proxy",
                      "data": { "username": "",
                                "password": "",
                                "endpoint": backenduri +
                                    "/oauth2/start" } })

This creates a Flask application which presents the service metadata on /metadata, /v1.0/metadata, /mymicroservice/metadata, and /mymicroservice/v1.0/metadata/, as well as all of those with .json appended.

3.2.1.4   Session object¶

Now, in order to actually access your data, you’re going to need to make your requests within a session with the appropriate authentication. Let’s assume that your caller is going to send you HTTP Basic Authentication headers, and you’re going to use those as username and password to the proxy.

You’ll need a place to store the session. Fortunately, Flask provides a mechanism for this: the app.config dict.

So, after initialization, you probably want:

 app.config["SESSION"] = None

3.2.1.5   Reauthorization¶

Next you need a _reauth() function, so if an HTTP operation fails with a 401 Unauthorized or 403 Forbidden, you can try to regenerate a session with your authentication data:

 def _reauth(app, username, password):
     """Get a session with authentication data"""
     oaep = app.config["AUTH"]["data"]["endpoint"]
     # Session here comes from BitlyOAuth2Proxy
     session = Session.Session(oauth2_username=username,
                               oauth2_password=password,
                               authentication_session_url=None,
                               authentication_base_url=oaep)
     session.authenticate()
     app.config["SESSION"] = session

When we create the actual fetch of backend data, we’ll see how to pull the headers off the request we got and create an authorization object for the session.

3.2.1.6   Error handler¶

Next we’ll add a basic error handler:

 @app.errorhandler(BackendError)
 def handle_invalid_usage(error):
    """Custom error handler; bubble up status code, jsonify rest."""
     response = jsonify(error.to_dict())
     response.status_code = error.status_code
     return response

Now, whenever you want to return an error based on something you got from the service, create a new apikit.BackendError.

3.2.1.7   Healthcheck¶

Since this application is eventually going to run under Google Container Engine using an Ingress TLS terminator and router (well, this is our current state, and it is our assumption that it will be that way long-term, anyway), you want the actual application root to return a 200 very quickly, because the Ingress controller will be pinging it often to determine service health (GCE’s Ingress defines a successful healthcheck as getting 200 from an HTTP GET /.

 @app.route("/")
 def healthcheck():
     """Default route to keep Ingress controller happy."""
     return "OK"

3.2.1.8   Service logic¶

Finally, let’s add the actual service. In addition to the routing and fetching logic, you will need to peel the authentication headers out of the inbound request and create a session with them, if you don’t already have a session with the correct authentication information.

{
    jobname
    metric
    value
}

 # Route it to the root too, in case we want to put it behind nginx
 #  or HAProxy or something that can do path rewriting.
 @app.route("/<jobname>/<metric>")
 @app.route("/mymicroservice/<jobname>/<metric>")
 def get_metric_for_job(metric=None, jobname=None):
     """Retrieve the metric and format it with JSON for return."""
     # Create a custom error if metric or jobname are not specified
     if metric is None or not metric or jobname is None or not jobname:
         raise BackendError(reason="Bad Request",
                            status_code=400,
                            content="Must specify metric and jobname.")
     # If we have authorization on the request, try to use it
     if request.authorization is not None:
         inboundauth = request.authorization
         currentuser = app.config["AUTH"]["data"]["username"]
         currentpw = app.config["AUTH"]["data"]["password"]
         # If we are already using this user/pw, don't bother.
         if currentuser != inboundauth.username or \
            currentpw != inboundauth.password:
             _reauth(app, inboundauth.username, inboundauth.password)
     else:
         raise BackendError(reason="Unauthorized", status_code=401,
                            content="No authorization provided.")
     session = app.config["SESSION"]
     # This is going to end up in the same function where backenduri
     #  is defined.  See below.
     url = backenduri + "/api"
     params = { "metric": metric,
                "job": jobname }
     resp = session.get(url, params=params)
     if resp.status_code == 403 or resp.status_code == 401:
         # Try to reauth
         _reauth(app, inboundauth.username, inboundauth.password)
         session = app.config["SESSION"]
         resp = session.get(url, params=params)
     if resp.status_code == 200:
         # Success!
         rdict = { "metric": metric,
                   "jobname": jobname,
                   "value": resp.text() }
         return jsonify(rdict)
     else:
         raise BackendError(reason=resp.reason,
                            status_code=resp.status_code,
                            content=resp.text)

3.2.1.9   Server function¶

 def server(run_standalone=False):
     # Refer to the earlier pieces of this document for the code
     #  fragments that need to be inserted in place of the comments.
     #
     # APIFlask instantiation to create the application goes here...
     # ...then add SESSION to the config dict...
     # ...next, add an error handler...
     # ...then, your healthcheck...
     # ...finally, your actual route.
     #
     # And now a bit of new code, to run the service if invoked standalone:
     if run_standalone:
         app.run(host='0.0.0.0', threaded=True)

The imports go at the top of server.py, of course, and the _reauth() function stands on its own, not nested inside server().

3.2.1.10   Standalone invocation¶

The only other thing you really need is to add a Python shebang and invoke server() standalone if the script is run from the command-line. Making standalone() its own function makes setup.py a bit prettier.

#!/usr/bin/env python
"""My microservice wrapper."""

# Imports go here...
# ...server function goes here...
# ...reauth goes here.

def standalone():
    """Run standalone; makes setuptools invocation a little prettier."""
    server(run_standalone=True)


if __name__ == "__main__":
    standalone()