Quickstart: Your First Full Featured Python API

In a terminal window, clone the repository: git clone git@github.com:jpollock/akka-serverless-getting-started-python.git;

In the same terminal, navigate to the project folder: cd akka-serverless-getting-started-python;

Run the containers: docker-compose up -d.

cd akka-serverless-getting-started-python if not already there;

Create a virtual environment: python3 -m venv myenv;

Load the newly created environment: source myenv/bin/activate;

Install the necessary Python modules: pip install -r requirements.txt

Start the API: start.sh

Open the api_spec.proto file in your favorite code or text editor.

Define the schema of the request. The data sent to the API, in this case, is quite simple: a name. This data will either be part of a JSON payload or part of the URI or request parameters. Fetching User Profile data by a person’s name wouldn’t work n the real world - too many Jeremys out there! - so let’s change name to be a parameter more like an id. Let’s change name to user_profile_id.

message MyRequest {
    string user_profile_id = 1;
}

Now let’s move on to what data we expect to send back as a response to this request for User Profile data. text seems to not be a great choice so let’s change that to name (which nows seems appropiate!). And a name for a User Profile is rather bare bones so we will add some other attributes of a User Profile that we would like to see.

message MyResponse {
   string name = 1;
   string status = 2;
   bool online = 3;
}

We have a request and a response. Now we need the API! The starter code in the file is for a POST /hello API call. We need to make some changes.

Generate Python stub code by running, from terminal window, in the project directory: compile.sh.

Open the api_impl.py so that we can add our business logic.

Change @action.unary_handler("Hello") to @action.unary_handler("GetUser"). This essentially performs the routing logic, to map the incoming API request to the URI path specified in the api_spec.proto to the function that will handle the request.

Change def hello to def fetch_user. This is not necessary since we already have the routing done through the above change but it makes our code more sensible to the reader.

At the top of the file, right before # imports fom Akka Serverless SDK add a new line: import random. We will just use some random data for fun.

In the now named users function, change the line, resp = MyResponse(text= "Do you want to play a game, " + command.name + "?") to resp = MyResponse(name= "My Name", status= random.choice(['active', 'inactive']), online= bool(random.getrandbits(1)))

Start the API (and proxy) with the start.sh command in the terminal.

Open the api_spec.proto file in your favorite code or text editor.

Add a new message request, to capture the information we want to pass into the API: name of the User, status of the User, e.g. a customer or not, and list of devices.

message UserProfile {
    string user_profile_id = 1;
    string name = 2;
    string status = 3;
    repeated Device devices = 4;
}

message Device {
    string id = 1;
    string name = 2;
}

Annotate the user_profile_id parameter in both the UserProfile and MyRequest messages such that the parameter, user_profile_id, is denoted as the identifier that Akka Serverless should use for Value Entity (KV) storage and manipulation. The annotation is: [(akkaserverless.field).entity_key = true]. See below for example on where to put.

message UserProfile {
    string user_profile_id = 1 [(akkaserverless.field).entity_key = true];
    string name = 2;
    string status = 3;
    repeated Device devices = 4;
}

message Device {
    string id = 1;
    string name = 2;
}

message MyRequest {
    string user_profile_id = 1 [(akkaserverless.field).entity_key = true];
}

Update the MyResponse so that it can be used in this new API as well; we are just adding additional data parameters that we will include in the body of the response.

message MyResponse {
    string name = 1;
    string status = 2;
    bool online = 3;
    repeated Device devices = 4;
}

Add the API itself. We’ll two: a POST /users for creation of a UserProfle and PUT /users/{user_profile_id} for the update.

service MyApi {
    rpc GetUser(MyRequest) returns (MyResponse) {
        option (google.api.http) = {
            get: "/users/{user_profile_id}",
        };
    }
    rpc CreateUser(UserProfile) returns (MyResponse) {
        option (google.api.http) = {
            post: "/users",
            body: "*"
        };
    }
    rpc UpdateUser(UserProfile) returns (MyResponse) {
        option (google.api.http) = {
            put: "/users/{user_profile_id}",
            body: "*"
        };
    }

}

Generate code by running, from terminal window, in the project directory: compile.sh.

Open the api_impl.py so that we can add our business logic. First, change the implementation of our API from an Action to a Value Entity. Replace:

from akkaserverless.action_context import ActionContext
from akkaserverless.action_protocol_entity import Action

from akkaserverless.value_context import ValueEntityCommandContext
from akkaserverless.value_entity import ValueEntity

Add UserProfile in front of MyRequest in the import statement:

Change the API implementation type from Action to ValueEntity. Replace::

entity = Action(_MYAPI, [API_DESCRIPTOR])

entity = ValueEntity(_MYAPI, [API_DESCRIPTOR])

Initialize default data for the User Profile. After the import statements, add:

Update the entity definition to include both the type and the default data:

Since we’ve moved from Action to ValueEntity we need to change some things in our GetUser API code.

Add a new command handler for CreateUser.

Add a new command handler for UpdateUser.

Now let’s start our updated API: start.sh

Open up proto file

Add an empty service definition at the end of the file, called MyQueryApi:

service MyQueryApi {

}

Querying in Akka Serverless is based on a feature called (views)[https://developer.lightbend.com/docs/akka-serverless/reference/glossary.html#view]. Views are created automatically by Akka Serverless based on the events that occur, e.g. new data created, updated or deleted. As such, we have to define an API - not called directly by a developer - that will be used by Akka Serverless to connect the events to the query tables that will be created and managed. We do this using the eventing annotation. We will add this API endpoint to the MyQueryApi.

service MyQueryApi {
    rpc UpdateView(UserProfile) returns (UserProfile) {
        option (akkaserverless.method).eventing = {
            in: {
                value_entity: "user_profiles"
            }
        };
        option (akkaserverless.method).view.update = {
            table: "user_profiles"
        };
    }
}

The second part of our new MyQueryApi will be the actual API call that can be used by a developer to make the actual query. In this case, let’s do a simple query for fetching all of the users created by our MyApi. Name of the API is GetUsers, with no input parameters supported an a resonse of type UsersResponse. The annotation used, to define the query, is option (akkaserverless.method).view.query and the query is a simple select statement: SELECT * AS results FROM user_profiles.

rpc GetUsers(google.protobuf.Empty) returns (UsersResponse) {
    option (akkaserverless.method).view.query = {
    query: "SELECT * AS results FROM user_profiles"
    };
    option (google.api.http) = {
        get: "/users"
    };
}

In the above, we have a new message type that we have to define: UsersResponse. In this case, it is a simple list of UserProfile messages. The definition is:

message UsersResponse {
    repeated UserProfile results = 1;
}

Compile the stub code based on our updated protobuf:

compile.sh

Now we have our API defined and the eventing setup so the underlying data structures are populated. We connect this to code by updating our api_impl.py. We need to import some modules and then setup the View. You can add the below right after the from api_spec_pb2 import (UserProfile, MyRequest, MyResponse, _MYAPI, DESCRIPTOR as API_DESCRIPTOR) line. You could also put at the bottom of the file as well.

from akkaserverless.view import View
from api_spec_pb2 import (_MYQUERYAPI, DESCRIPTOR as FILE_DESCRIPTOR)

view = View(_MYQUERYAPI,[FILE_DESCRIPTOR])

The final step is to expose it to the Akka Serverless run-time. Update the api_service.py file to import the view and add it to the list of components served. The file should look like:

"""
Copyright 2020 Lightbend Inc.
Licensed under the Apache License, Version 2.0.
"""

from akkaserverless.akkaserverless_service import AkkaServerlessService
from api_impl import entity as myapi
from api_impl import view as myquery
import logging

if __name__ == '__main__':
    logging.basicConfig(level=logging.DEBUG)

    # create service and add components
    service = AkkaServerlessService()
    service.add_component(myapi)
    service.add_component(myquery)
    service.start()

Start the API service again: start.sh

Set your DOCKER_REGISTRY and DOCKER_USER environment variables:

export DOCKER_REGISTRY=<your Docker registry, e.g. docker.io>#
export DOCKER_USER=<your Docker registry username>

From the root project directory, build the docker container (the 0.0.1 is just the version number you want to use to tag the container):

docker_build.sh 0.0.1

Push the built container to the registry:

docker_push.sh 0.0.1

Sign in to your Akka Serverless account at: Akka Serverless Console

If you do not have a project, click Add Project to create one, otherwise choose the project you want to deploy your service to.

On the project dashboard click the "+" next to services to start the deployment wizard

Choose a name for your service and click Next

Enter the container image URL from the above step and click Next

Click Next (no environment variables are needed for these samples)

Check both Add a route to this service and Enable CORS and click Next

Click Finish to start the deployment

Click Go to Service to see your newly deployed service

From the "Service Explorer" click on the method you want to invoke

Click on "gRPCurl"

In the bottom section of the dialog, fill in the values you want to send to your service

In the top section of the dialog, click the "Copy to clipboard" button

Open a new command line and paste the content you just copied