Everyone has an opinion on the best way to do microservice architecture, including me. The following is a series of blog posts where I lay out an opinionated “template architecture” for how to do Microservices in a way that is scalable and sustainable.
The principles I find important are:
- API first
- Vendor agnostic
- Cheap to operate
- Standardised communication/service mesh layer
- Language and framework agnostic
- Black box testable
- Unit of deployment agnostic
The first post will be talking about how to make a super simple Swagger API definition and the use this to generate a Python Flask server.
The third post will talk about operational concerns including costs, portability, traceability, deployment, scale ability, backups, service discovery and registration etc…
The fourth post will talk about testing, both at the unit test level and at the “black box”/integration testing/end to end testing
The fifth post will talk about shared libraries and advanced topics
Defining a Trivial Swagger (OpenAPI) API
So, in order to get started, we can define an dummy API which lets us retrieve information about books. The below is a simple Swagger (also now the OpenAPI standard) API to do with books:
The example explicitly leaves out any authentication and only defines a single endpoint with a GET/POST verb and a single object type.
We can verify that our API definition is valid by opening the Swagger Online Editor and pasting it in the editor pane.
So, now we have an API, which defines a “contract” between the client and the server and in an ideal world we would put this into version control (either in it’s own repository or into a monorepo, depending on whether our CI/CD server could trigger off of paths).
Generating the Server Stub
Now that we have an API definition, we can make use of the swagger-codegen tool to use it to generate a Flask “server stub” which we can use as a template for our application. We can install swagger-codegen on OS X with the Homebrew package manager and the following command:
brew install swagger-codegen
After we’ve installed the codegen tool, we can run commands to generate the Flask server:
swagger-codegen generate \
-i https://gist.githubusercontent.com/srkiNZ84/3a8f7deb11cf368e25607cf0a66bc140/raw/cac66ce550489538f415734ded075fea192ae94f/book.yml \
The arguments passed to the command tell it to generate code, point it at our YML file containing the API definition and finally tell the command what kind of server code to generate. (For a list of all of the possible code/framework outputs have a look at the swagger-codegen documentation).
Assuming that the command runs successfully, you should have output such as the below:
We still need to install the Python Flask requirements and start up the server.
Looking at the contents of the directory, we can see that the generator has generated a Flask application as well as a Dockerfile and other code and configuration:
drwxr-xr-x 15 srdan wheel 480B 10 Aug 22:03 .
drwxrwxrwt 11 root wheel 352B 10 Aug 22:02 ..
-rw-r--r-- 1 srdan wheel 885B 10 Aug 22:03 .dockerignore
-rw-r--r-- 1 srdan wheel 786B 10 Aug 22:03 .gitignore
drwxr-xr-x 3 srdan wheel 96B 10 Aug 22:03 .swagger-codegen
-rw-r--r-- 1 srdan wheel 1.0K 10 Aug 22:03 .swagger-codegen-ignore
-rw-r--r-- 1 srdan wheel 349B 10 Aug 22:03 .travis.yml
-rw-r--r-- 1 srdan wheel 246B 10 Aug 22:03 Dockerfile
-rw-r--r-- 1 srdan wheel 1.1K 10 Aug 22:03 README.md
-rw-r--r-- 1 srdan wheel 1.6K 10 Aug 22:03 git_push.sh
-rw-r--r-- 1 srdan wheel 66B 10 Aug 22:03 requirements.txt
-rw-r--r-- 1 srdan wheel 785B 10 Aug 22:03 setup.py
drwxr-xr-x 10 srdan wheel 320B 10 Aug 22:03 swagger_server
-rw-r--r-- 1 srdan wheel 90B 10 Aug 22:03 test-requirements.txt
-rw-r--r-- 1 srdan wheel 143B 10 Aug 22:03 tox.ini
We need to install the Python dependencies with “pip”:
pip3 install -r requirements.txt
To start the server, we can run:
python3 -m swagger_server
We should then be able to see our application running at the URL:
With the Swagger API definition available at:
We can then start filling out the logic of our application to make it behave like we want.