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

Development checklist.

  1. Goals of the microservice.
  2. Implementation.
  3. Dockerfile.
  4. microservice.yaml.

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:

  1. HTTP. Recommended for most projects.
  2. RPC. Recommended when performance is critical.
  3. 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 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.

The Dockerfile

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

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, x and y.

omg: 1 

  version: 1.0.1
  title: Calculator 
  description: This is a sample calculator
    name: MIT

    help: Adds two integers
      method: post
      path: /add
      port: 5000
        type: int
        required: true
        in: requestBody
        type: int
        required: true
        in: requestBody
      type: string

    command: ["flask", "run", "--host="]

OMG! We did it πŸŽ‰ The microservice.yml file has defined the following things about our service:

  1. How to start the HTTP server.
  2. The actions this microservice exposes.
  3. The arguments for each action.
  4. The strategy used to perform each action.
  5. 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 omg-cli!

# First, install the omg cli
$ npm install -g omg

# Now run omg
$ omg run add -a 'x=1' -a 'y=2'

That's it! πŸš€πŸŽ‰ Your service is now OMG compliant.

Publish to Story Hub

The Story Hub is a registry of services that are all OMG compliant that can be used and executed on the Story Cloud.

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>

Congratulations! You just launched your microservice on the Story Cloud!

πŸš€ Continue your journey building smarter applications on Storyscript: