In previous posts we learned how to create a microservice in a notebook using the Jupyter kernel gateway. This will be the foundation for today’s post where we will be creating a notebook microservice with Swagger, a set of tools for representing REST APIs. With this this approach, notebook authors can create and deploy APIs that are easy-to-comsume by other developers.
There are many components to Swagger, but today we will be using three. The first component, the Swagger Specification, is a specification we will use to describe out microservice. The second is a code generation plugin to generate our notebook. And finally, we will use the Swagger UI to interact with our newly deployed service.
Setup and Introduction
There is some initial setup needed for this demo:
While all of that is installing, let’s look at reasons for integrating Swagger in our microservice workflow.
- Clear API Definition – The Swagger Specification is a standard way for describing our microservice API. This allows for the rapid and collaborative design of what our API will look like.
- Quick Code Generation – Using a standard way to describe our microservice opens up a suite of tools for generating code. Today we will generate a notebook, but there are also tools for generating other client and server side pieces of code.
- Easy API Testing – Another advantage of describing our microservice in a standard way is the use of tools for testing. An example of this is the Swagger UI, which we will use today, for manually verifying the behavior of API endpoints.
Designing The Microservice
Our microservice will be used to create and get random quotes. Our service is defined by the following API endpoints:
- An endpoint to display random quote
- An endpoint to add new quotes
- And endpoint to get a quote
- An endpoint to update a quote
We now need a way to describe this API so Swagger can generate a specification for us. I used the Swagger Editor to design this API in YAML. The code snippet below is the definition for the full API specification.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
swagger: ‘2.0’ info: version: 0.0.1 title: ‘Words Of Wisdom’ description: An API for recording and reflecting quotes. contact: name: Corey Stubbs email: cstubbs@us.ibm.com url: ‘https://github.com/Lull3rSkat3r’ paths: /random: get: description: Returns a random quote responses: ‘200’: description: A string containing the quote schema: type: string /quote: post: description: Adds a quote parameters: – name: body in: body description: The quote to be added to the collection required: true schema: type: string responses: ‘201’: description: Returns the id of the newly create quote, which can be used to access the quote schema: type: integer /quote/{id}: get: description: Gets the quote parameters: – name: id in: path description: The quote to be added to the collection required: true type: string responses: ‘201’: description: Returns the id of the quote, which can be used to access the quote schema: type: integer put: description: Updates the content of quote. parameters: – name: id in: path description: The quote to be added to the collection required: true type: string – name: body in: body description: The new value of the quote required: true schema: type: string responses: ‘204’: description: The quote has successfully been updated. |
With the microservice defined, we can export it to a JSON file. You can do this in the Swagger Editor by going to File -> ‘Download JSON’.
Generating The Notebook
Once you have the JSON file describing the microservice, navigate to the kernel gateway demos project on your system. You will need to open a command line utility here and go to the directory swagger–notebook–service/jupyter–swagger–codegen. From this directory we will generate the notebook to implement our microservice. The language for the generated notebook defaults to Python 3. You can generate the notebook with the following command:
|
1 |
SWAGGER_SPEC=path/to/swagger.json make gen |
path/to/swagger.json is the JSON file you downloaded earlier from the Swagger Editor. If you did not create your own swagger.json file, use this url to download a completed copy. The command should have generated the following files in target/swagger/python3/WordsOfWisdom/src/:
- WordsOfWisdomApi.ipynb – The notebook where the service will be implemented
- package.sh – Bundles the notebook with the kernel gateway into a Docker container
- run.sh – Runs the Docker container built by package.sh
- Dockerfile – A Dockerfile that defines Docker container image
Authoring And Running The Microservice
For the sake of brevity, there is a sample notebook with the implemented API endpoints. You can download this file and put the contents into the WordsOfWisdomApi.ipynb file.
From here you can build and deploy the microservice locally with Docker by running:
|
# Run the commands below within: target/swagger/python3/WordsOfWisdom/src/ # Build the docker container sh package.sh # Run the built container sh run.sh |
When everything is built correctly, you should see output similar to the following:
|
[KernelGatewayApp] Registering endpoint_path: /random, methods: ([‘GET’]) [KernelGatewayApp] Registering endpoint_path: /quote, methods: ([‘POST’]) [KernelGatewayApp] Registering endpoint_path: /quote/(?P<id>[^/]+), methods: ([‘PUT’, ‘GET’]) [KernelGatewayApp] The Jupyter Kernel Gateway is running at: http://0.0.0.0:8888 |
With the service successfully running, you will be able to access the API endpoints. Use the ip address for your Docker host and go to: http://YOUR_DOCKER_HOST:8888/random. This endpoint will display a random quote, served from our notebook.
Consuming The Swagger Spec
Our final step will be to use the Swagger UI to interact with our API. The kernel gateway will automatically generate a simple Swagger Specification for consumption through the Swagger UI. The specification can be found at http://YOUR_DOCKER_HOST:8888/_api/spec/swagger.json. You will need to enter the spec URL into the Swagger UI. The picture below shows how to use the Swagger UI to make requests to the microservice.
Note: The generated swagger spec is still under development and you will not be able to interact with all endpoints. As a temporary alternative, you can use the Swagger Editor for interacting with the microservice. If you have a need for a requirement pull requests and issues are welcome.
Summary
In this post you have seen how integrating Swagger into the microservice workflow has helped our development process. If you have any questions or want to get involved with the kernel gateway visit our github repo.
Learn More
Lull3rSkat3r