is a set of requirements that define a microservice component pluggable in an API gateway

Microservice-component-definition.md

Microservice component

is a set of requirements that define a microservice component pluggable in an API gateway

Definition

A Microservice component is a microservice that serves a REST API behind an API Gateway. The API Gateway is, for instance, binded to domain api.example.org and it must serve resources over https. The chosen technology is nginx but can be any reverse proxy.

Every microservice

1. Can be implemented in any programming language.
2. Has its git versioned folder that contains a service.json file with the following entries
   1. basePath {String} starting with a /
   2. port {Number} greater than 1024
3. The service.json file is read on service startup: all endpoints are served on specified port and starts with its basePath.
4. The versioned folder must contain a README.md with information about:
   • how to install
   • how to start and stop the service
   • API endpoints
   • and a reference to this document. Something like

# name

> description

## Installation

How to install service and its dependencies.

## Service

How to start and stop the service.

## API

### `GET /foo`

### `POST /bar`

<sub>This service adhere to the [Microservice component][microservice_component] definition.</sub>

[microservice_component]: https://gist.github.com/fibo/6c4c15eeb4016309d7378d579ff143d6

To generate the API Gateway nginx config file, launch something like

$ export PORT="console.log(require('./service.json').port)"
$ export BASE_PATH="console.log(require('./service.json').basePath)"
$ cat <<EOF > /etc/nginx/conf.d/api.example.org
server {
    listen 80;

    server_name api.example.org;

    location $BASE_PATH {
        proxy_pass http://localhost:$PORT;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
EOF
unset BASE_PATH
unset PORT

See for example this express template.

_{Find last version of this document here.}