Introducing the Open Microservice Guide.
The Open Microservice Guide (OMG for short) is an open standard for designing microservices. We believe microservices should have explicit actions, arguments and outputs while having strong documentation on environments, interfacing and life-cycling. The
microservice.yml is the documentation and guide to your microservice.
For more information on the mission of the OMG and the schema please visit https://microservice.guide
- Goals of the microservice.
Goals of our service.
By definition, a microservice is designed to be domain specific with operations that are highly specialized. This is what makes microservices so appealing: they are simple and specific. Typical microservices are one service with many actions, for example, Twitter as a service with all the API endpoints as actions (tweet, follow, stream, etc).
Example. To keep it simple, let's make a microservice that just adds two numbers.
# Actions 1. Add two integers; returns the sum.
Your ideas can be as extravagant as you'd like - just take a look at some of these examples.
When designing your microservice, the OMG makes use of three general strategies to communicate with it:
- HTTP. Recommended for most projects.
- RPC. Recommended when performance is critical.
- Command line arguments. When the service already has a strong CLI footprint.
Example. To keep things very simple, we are going to interface with HTTP and use Python as our language.
Your microservice can be written in any language, as long as it can be interfaced with by using one of the strategies above.
# -*- coding: utf-8 -*- from flask import Flask, request app = Flask(__name__) @app.route('/add', methods=['POST']) def add(): return str(int(request.values['x']) + int(request.values['y']))
Save this file as
app.py. Great job! 👍 Now that we have the code of our microservice written, let's continue with getting it OMG approved.
Tip 💡 Searching GitHub for an existing open source library exposing the API can be a quick way to build your microservice. See the Slack or Twitter microservice for inspiration.
Docker is a widely adopted containerization tool. The easiest way to think about it is a box that contains everything to run the service.
Example. Let's now create our
Dockerfile producing a container for our microservice.
FROM python:alpine RUN pip install flask COPY app.py /app.py
The great thing about Docker, and the reason why we use it, is once we build our service with Docker and "containerize" it, it can executed on any machine, and OS so long as Docker is installed. Here is some more information of the idea of "containerize".
The microservice.yml file.
Let's write a file (in YAML) that defines exactly what our service does and, as a beautiful side effect, auto-generates our documentation. This file should be saved as microservice.yml. The syntax and schema of this file is defined by the OMG. 🌈
Example. We need to define an action:
add which takes two arguments,
omg: 1 info: version: 1.0.1 title: Calculator description: This is a sample calculator license: name: MIT url: https://opensource.org/licenses/MIT actions: add: help: Adds two integers http: method: post path: /add port: 5000 arguments: x: type: int required: true in: requestBody y: type: int required: true in: requestBody output: type: string lifecycle: startup: command: ["flask", "run", "--host=0.0.0.0"]
OMG! We did it 🎉 The microservice.yml file has defined the following things about our service:
- How to start the HTTP server.
- The actions this microservice exposes.
- The arguments for each action.
- The strategy used to perform each action.
- The output for each action.
This is a small, yet powerful example. See more examples in GitHub @microservice.
Testing your microservice.
It goes without saying that testing your microservice is important. The OMG helps here too. We have designed the
omg-cli which is used as a sandbox for testing your microservice implementation. It's a powerful tool that can be used to mock a production-like environment that interfaces with your service according to its
microservice.yml. Let's take a look at the
# First, install the omg cli $ npm install -g omg # Now run omg $ omg run add -a 'x=1' -a 'y=2' 3
That's it! 🚀🎉 Your service is now OMG compliant.
Publish to Story Hub
Signup/Login to Story Hub (it's free) and follow the directions to list your service. Once you have listed your service, you can use it in your first Storyscript
Run on Story Cloud
Write a Storyscript including your service by replacing the
MyOrg/MyService below with the owner/repo you registered the service under.
when http server listen path:'/add' as request result = MyOrg/MyService add x:request.arguments['x'] y:request.arguments['y'] request write content:result
The script above is a serverless endpoint for your microservice. Let's launch it with the Story CLI (install directions here).
$ story login $ story apps create $ story deploy
👍Nice job! Let's hit your application endpoint:
$ curl https://<app_name>.storyscriptapp.com?x=5&y=7 12
Congratulations! You just launched your microservice on the Story Cloud!
🚀 Continue your journey building smarter applications on Storyscript: