{"id":13033,"date":"2022-04-11T08:56:35","date_gmt":"2022-04-11T15:56:35","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=13033"},"modified":"2025-06-13T21:25:00","modified_gmt":"2025-06-14T04:25:00","slug":"build-a-python-microservice-with-couchbase-part-2","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/build-a-python-microservice-with-couchbase-part-2\/","title":{"rendered":"Build A Python Microservice With Couchbase \u2013 Part 2"},"content":{"rendered":"

In the first installment of this series<\/a>, we discussed the drivers behind creating microservices, and why Couchbase is the perfect datastore to use with a microservice architecture. With their stateless nature, they can be deployed anywhere and horizontally scaled as needed. While you could write a microservice in any language, to fit into an agile workflow where you need to deliver functionality fast, you should choose a language known by most developers and allow for rapid development. Since Python and JavaScript are two popular languages, either would be a good fit. In this blog series, we are focusing on Python.<\/p>\n

Distributed performance considerations<\/h2>\n

Application performance requirements are important, but they are sometimes difficult to quantify. A simple example is a report that runs in X hours; however, it should run in Y minutes due to business requirements. That example is easy to quantify and provides a clear target for improvement. When you have a geographically distributed architecture, if a component can support X requests per second, that does not mean anything. Considering the number of variables in a geographically distributed application<\/a>, you need to take a step back and start with something you can quantify; for example, you want a smartphone app to fully load in X seconds, or you want a web page to fully load in Y seconds. Then work backward to see what is needed to make that happen.<\/p>\n

Python microservice performance considerations<\/h2>\n

When you create a microservice in Python, you have some options to consider before you start coding. You can either write all your own Python code to create the service or use a Python API framework such as Flask or FastAPI. In the first installment of this series<\/a>, I provided an example of the first option. I will call this the “full code” option. In this second part of the series, I will introduce an implementation of the simple User Profile service using FastAPI. I chose FastAPI over Flask for this Blog because most consider it faster, and I thought it would be fun to give it a try.<\/p>\n

But first, let’s focus on our original “full code” example. We used Python’s HTTPServer<\/em> class to create a basic Web Server to respond to our API calls. For our API, we decided to use paths (as opposed to parameters or posting a JSON body) as it is fast and easy to parse. Our simple User Profile API does not need to provide much \u2013 just a few methods to look up a user profile and get the data. I included options for lookup by ID<\/em>, Nickname<\/em> or Username<\/em>. In real life, requirements will vary based on how the upstream application is designed.<\/p>\n

The full code program has two logical areas \u2013 code that is executed once and the code executed for each request \u2013 namely the do_GET function. For expedience, we won’t focus on the limited execution code, but we will focus on the do_GET function and its satellite functions. With Python’s HTTPServer<\/em> class, this function will be called with each request. The request path will be in the class and accessible via self.path<\/em> and the headers are in self.headers<\/em>. If you are just getting started with Python, self<\/em> is like this in Java \u2013 it references the calling instance of the class.<\/p>\n

The service will need to iterate on the contents of the path string so it can do the appropriate lookup and return the data. Thanks to the beauty of Couchbase’s JSON native design, we don’t have to do much, if anything, to the data before we send it. So, we will focus on how to inspect the path. Python has a lot of built-in options for string processing which enable you to write pretty code, but not necessarily the fastest code. Python is an interpreted language (it runs directly from the source) so statements make a difference.<\/p>\n

Let’s look at two options for path string processing – the startswith<\/em> and split<\/em> methods.<\/p>\n

% python3 -m timeit -s 'text=\"\/api\/v1\/id\/4\"' 'text.startswith(\"\/api\/v1\/id\/\")'\r\n2000000 loops, best of 5: 111 nsec per loop\r\n\r\n% python3 -m timeit -s 'text=\"\/api\/v1\/id\/4\"' 'text.split(\"\/\")[-1]'\r\n1000000 loops, best of 5: 205 nsec per loop<\/pre>\n
The split is more expensive, but we are going to have to do it, so it would be best to do it only once. We can then avoid calling anything else by using the array returned from the split as opposed to startswith<\/em>.<\/p>\n
% python3 -m timeit -s 'True if 1 == 5 else False'\r\n50000000 loops, best of 5: 6.07 nsec per loop<\/pre>\n
Conditional statements are fast, so while it may not look pretty, we will do a single split and then build an if\u2026elif\u2026else<\/em> structure to iterate through the path. We will write short helper functions to do a query or key-value get and return the JSON data to the requestor with minimal processing.<\/p>\n
Also, to make our microservice secure, we will add a Bearer Token. We would use something like OAuth with Bearer and JWT tokens in a real environment. For our example, we will greatly simplify this and add a collection to our schema with a fixed token. The service will query this token on startup and only respond to requests that provide this token as a Bearer token. Finally, if needed, we will add a health check path that responds with an HTTP 200<\/em> so we know our service is healthy.<\/p>\n
 \u00a0\u00a0 def do_GET(self):\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 path_vector = self.path.split('\/')\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 path_vector_length = len(path_vector)\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 if path_vector_length == 5 and path_vector[3] == 'id':\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 if not self.v1_check_auth_token(self.headers):\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 self.unauthorized()\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 request_parameter = path_vector[4]\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 records = self.v1_get_by_id('user_data', request_parameter)\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 self.v1_responder(records)<\/pre>\n
Containerizing the Python microservice<\/h2>\n
I decided to use Kubernetes to test the service, so I had to build containers with the various implementations of the API. There is a published Python container that can be used as a base. Some OS prerequisites will have to be installed before the required Python packages. The Python container is based on Debian so the prerequisite packages can be installed with APT. Then pip<\/em> can be called to install the required Python packages. The service port will need to be exposed, and finally, the service can be run as it would be run from the command line. To containerize the service, it will need an additional modification to support environment variables as this is the preferred method for passing parameters into a container.<\/p>\n
This is an example of the Dockerfile for the full code service:<\/p>\n
FROM python:3.9-bullseye\r\nRUN apt update\r\nRUN apt install elpa-magit -y\r\nRUN apt install git-all python3-dev python3-pip python3-setuptools cmake build-essential libssl-dev -y\r\nWORKDIR \/usr\/src\/app\r\nADD . \/usr\/src\/app\r\nRUN pip install --no-cache-dir -r requirements.txt\r\nEXPOSE 8080\r\nCMD .\/micro-svc-demo.py\r\nThe service can then be run passing the parameters through the environment:\r\ndocker run -d --name microservice \\\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 -p 8080:8080 \\\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 -e COUCHBASE_HOST=$COUCHBASE_HOST \\\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 -e COUCHBASE_USER=$COUCHBASE_USER \\\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 -e COUCHBASE_PASSWORD=$COUCHBASE_PASS \\\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 -e COUCHBASE_BUCKET=$COUCHBASE_BUCKET \\\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 testsvc<\/pre>\n
FastAPI<\/h2>\n
Some time ago, WSGI (Web Server Gateway Interface) was created for Python web frameworks. It enabled a developer to only focus on building web applications instead of all the other lower-level tasks required with a web server. That standard was extended into ASGI (Asynchronous Server Gateway Interface), which supports asynchronous Python programming and therefore is well suited for stateless applications such as REST APIs.<\/p>\n
Uvicorn<\/a> is an ASGI web server implementation for Python, and FastAPI integrates with Uvicron to create a rapid API development platform. I decided to use this to create a second API implementation to compare to the entire code version. Since it fully supports asynchronous Python, it also plays well with the Couchbase Python SDK, which fully supports asynchronous programming.<\/p>\n
Using this framework accelerates development because much less code is needed than the full code version. Some functions to connect to Couchbase are required, but beyond that, decorated app methods are used to interact with the FastAPI instance calling minimal code segments to fetch and return data. As with the full code version, the service connects to Couchbase once and uses the resulting collection methods to get data. The on_event<\/em> method is used on startup to connect to Couchbase, retrieve the auth token, and set all the needed variables.<\/p>\n
@app.on_event(\"startup\")\r\nasync def service_init():\r\n\u00a0\u00a0\u00a0 key_id = '1'\r\n\u00a0\u00a0\u00a0 cluster[1] = await get_cluster()\r\n\u00a0\u00a0\u00a0 collections['service_auth'] = await get_collection(cluster[1], 'service_auth')\r\n\u00a0\u00a0\u00a0 doc_id = f\"service_auth:{key_id}\"\r\n\u00a0\u00a0\u00a0 result = await collections['service_auth'].lookup_in(doc_id, [SD.get('token')])\r\n\u00a0\u00a0\u00a0 auth_token[1] = result.content_as[str](0)\r\n\u00a0\u00a0\u00a0 collections['user_data'] = await get_collection(cluster[1], 'user_data')\r\n\u00a0\u00a0\u00a0 collections['user_images'] = await get_collection(cluster[1], 'user_images')<\/pre>\n
Once the startup actions are complete, short functions for each possible request path are invoked through app method calls. The path parameter is extracted from the path and passed to the function, along with a dependency on the function to check the auth token. With this implementation, only environment variables are used to pass connection parameters.<\/p>\n
@app.get(\"\/api\/v1\/id\/{document}\", response_model=Profile)\r\nasync def get_by_id(document: str, authorized: bool = Depends(verify_token)):\r\n\u00a0\u00a0\u00a0 if authorized:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 profile = await get_profile(collection=collections['user_data'], collection_name='user_data', document=document)\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 return profile<\/pre>\n
The container for this implementation can use the same base as the full code version and install the same dependencies; however, it will have a few extra Python package requirements and the service is invoked through Uvicorn.<\/p>\n
FROM python:3.9-bullseye\r\nRUN apt update\r\nRUN apt install elpa-magit -y\r\nRUN apt install git-all python3-dev python3-pip python3-setuptools cmake build-essential libssl-dev -y\r\nWORKDIR \/usr\/src\/app\r\nADD . \/usr\/src\/app\r\nRUN pip install --no-cache-dir -r requirements.txt\r\nEXPOSE 8080\r\nCMD uvicorn service:app --host 0.0.0.0 --port 8080<\/pre>\n
Setting up Node.js to test endpoints<\/h2>\n
The blog post is about Python, but it would be helpful to have a non-Python comparison for the API so for this I decided to use Node.js; it is asynchronous and works well with APIs. The Node.js implementation uses the Express module to create a Web Server, and in a similar fashion to FastAPI it uses the app.get<\/em> method for all supported paths. It calls a function to check the auth token first, and if successful it calls a function to get the requested data.<\/p>\n
app.get('\/api\/v1\/nickname\/:nickname', checkToken, getRESTAPINickname);\r\napp.get('\/api\/v1\/username\/:username', checkToken, getRESTAPIUsername);\r\napp.get('\/api\/v1\/id\/:id', checkToken, getRESTAPIId);\r\napp.get('\/api\/v1\/picture\/record\/:id', checkToken, getRESTAPIPictureId);\r\napp.get('\/api\/v1\/picture\/raw\/:id', checkToken, getRESTAPIImageData);\r\napp.get('\/healthz', getHealthCheckPage);<\/pre>\n
There is a module for the Couchbase functions located in a JavaScript file, and the functions for the supported API calls are also in modules in separate JavaScript files. Like with Python, there is a Node container that is used as a base and the NPM utility maintains the dependencies and starts the service.<\/p>\n
FROM node:16.14.2\r\nWORKDIR \/app\r\nADD . \/app\r\nRUN rm -rf \/app\/node_modules\r\nRUN npm install -g npm@latest\r\nRUN npm install\r\nEXPOSE 8080\r\nCMD npm start<\/pre>\n
Kubernetes to spinup Couchbase autonomously<\/h2>\n
As mentioned earlier, Kubernetes was chosen to test the service implementations. This enabled accelerated testing due to the ability to rapidly deploy and scale the services for different test scenarios. There are two options for using Couchbase with Kubernetes. The Couchbase Autonomous Operator can be used to deploy Couchbase into the Kubernetes environment, or the service can connect to an external cluster. The service was tested with an external cluster that was deployed in the same cloud VPC. All nodes were in the same cloud region, and both the Couchbase cluster nodes and Kubernetes nodes were deployed across availability zones to simulate what would likely be seen in a real-world deployment.<\/p>\n
\"Using<\/a><\/p>\n
Three deployment YAML files were created to deploy the three implementations. Each deployment YAML creates a namespace for the service. It uses a secret for the Couchbase password. The service is deployed with 4 replicas initially. As it is a stateless microservice, it can scale up and down as needed. Traffic is directed to the service with a load balancer. As the Kubernetes environment used was integrated with a cloud provider, each deployment also provisioned a cloud load balancer for the service.<\/p>\n
apiVersion: v1\r\nkind: Namespace\r\nmetadata:\r\n\u00a0 name: demopy\r\n---\r\napiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n\u00a0 name: demopy-secrets\r\n\u00a0 namespace: demopy\r\ntype: Opaque\r\ndata:\r\n\u00a0 adminPassword: aBcDeFgH=\r\n---\r\napiVersion: apps\/v1\r\nkind: Deployment\r\nmetadata:\r\n\u00a0 name: demopy\r\n\u00a0 namespace: demopy\r\nspec:\r\n\u00a0 replicas: 4\r\n\u00a0 selector:\r\n\u00a0\u00a0\u00a0 matchLabels:\r\n\u00a0\u00a0 \u00a0\u00a0\u00a0app: demopy\r\n\u00a0 strategy:\r\n\u00a0\u00a0\u00a0 type: RollingUpdate\r\n\u00a0\u00a0\u00a0 rollingUpdate:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 maxUnavailable: 25%\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 maxSurge: 1\r\n\u00a0 template:\r\n\u00a0\u00a0\u00a0 metadata:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 labels:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 app: demopy\r\n\u00a0\u00a0\u00a0 spec:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 containers:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 - name: demopy\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 image: mminichino\/demopy:1.0.5\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 imagePullPolicy: Always\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ports:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 - name: app-port\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 containerPort: 8080\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 env:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 - name: COUCHBASE_HOST\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 value: 1.2.3.4\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 - name: COUCHBASE_USER\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 value: Administrator\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 - name: COUCHBASE_PASSWORD\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 valueFrom:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 secretKeyRef:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 name: demopy-secrets\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 key: adminPassword\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 - name: COUCHBASE_BUCKET\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 value: sample_app\r\n---\r\napiVersion: v1\r\nkind: Service\r\nmetadata:\r\n\u00a0 name: demopy-service\r\n\u00a0 namespace: demopy\r\n\u00a0 labels:\r\n\u00a0\u00a0\u00a0 app: demopy\r\nspec:\r\n\u00a0 selector:\r\n\u00a0\u00a0\u00a0 app: demopy\r\n\u00a0 ports:\r\n\u00a0 - name: http\r\n\u00a0\u00a0\u00a0 port: 8080\r\n\u00a0\u00a0\u00a0 targetPort: 8080\r\n\u00a0 type: LoadBalancer<\/pre>\n
Using the deployment YAML files, the service can be deployed and scaled as needed with the Kubernetes CLI. Optionally if this was an actual production environment, tools such as autoscaling and advanced load balancing could be used to control and access the deployment.<\/p>\n
$ kubectl apply -f demopy.yaml\r\n$ kubectl scale deployment --replicas=8 demopy -n demopy<\/pre>\n
Cluster performance results<\/h2>\n
Before testing the services, the Couchbase cluster was tested from the Kubernetes cluster to create a baseline. YCSB workload B was used (which is primarily key-value get<\/em> operations) and it yielded 156,094 ops\/s. API testing was done with Apache JMeter. The ID API call was used to keep it simple, and the JMeter random number generator was leveraged to create test runs against random user profiles. The test scenario was time bound with a run time of three minutes where it would generate unrestrained load against the load balancer service requesting random user profiles with no ramp-up (the load was constant for the whole test duration).<\/p>\n
\"Setting<\/a>\"Testing<\/a><\/p>\n
For the first set of tests, the JMeter test parameters were unchanged, and what varied was the scale of the three API implementations. Testing started with 4 Pods for each implementation deployment and scaled up to 8 and finally 16 Pods. All the implementations scaled throughput as the Pods scaled in the deployment.<\/p>\n
\"Couchbase<\/a><\/p>\n
Node.js fared the best with this test strategy as it had the lowest average latency. One millisecond is not a lot of latency, nor is 12 milliseconds. But with a fixed number of generator threads creating over 1 million requests in three minutes, milliseconds have a cumulative effect. However, please bear in mind that this is an extreme test. These are just data points. What was surprising was that the full code Python service kept pace with the FastAPI implementation.<\/p>\n
\"Couchbase<\/p>\n
Since the first test scenario demonstrated that both the full code Python and FastAPI implementations were scalable, the second round of tests scaled the number of request threads with a fixed number of 32 service Pods. With this test scenario, the Python-based services could scale near 10,000 requests per second.\"Couchbase<\/a><\/p>\n
Conclusions<\/h2>\n
I think that Python is an excellent option for moderate load services. With all the testing done, the Kubernetes cluster nodes had ample available CPU and memory, so there was plenty of headroom to scale the service as needed. For implementations that require massive scale at the lowest latency, then Node.js may be a better option. Couchbase supports all the prevalent languages, so just as I was able to easily code three microservice implementations, anyone can use multiple languages and frameworks and integrate Couchbase with ease.<\/p>\n
Up Next<\/h3>\n
In the next post in this blog series, I will talk about generating random test data for the microservice schema. Here are links to the resources mentioned in this post:<\/p>\n