The Timezynk backend is composed of a number of microservices each presenting independent APIs. The guidelines come from 12 Factor apps, please read that resource first. Here are the rules every microservice in the ecosystem MUST follow:

API namespacing and versioning

The microservice should publish its API under a namespace and version, for example:

/api/<microservice name>/v1/

Configuration

All configuration should be done using environment variables. When starting the service with one or more required variables unset, it should print all used environment variables. Some environment variables are standardized in the production environment and must have exactly these names, if they are used:

MONGO_URL : MongoDB url for the cluster and database to use, i.e. mongodb://mongodb/<microservice name>

TZBACKEND_URL : URL pointing to the root of the microservice load balancer, i.e. https://api.timezynk.com/api

CLIENT_ID : OAuth2 Client ID for authenticating with tzbackend

CLIENT_SECRET: Oauth2 Client Secret for authenticating with tzbackend

BIND_PORT: The TCP port to listen for connections on

NSQLOOKUP_SERVERS: List of NSQLookup servers for connection to the message queue.

Storage

If the microservices needs to persist data, it MUST do so using mongodb. Every microservice MUST use its own mongodb database and is forbidden to read or connect to any other database.

Communication

Communication with other microservices are done over the published HTTP APIs or over the NSQD message queue. If the service depends on coordination of several other services, assume that one of them could be down and cache the data locally before contacting the other services.

Prometheus metrics

All microservices should publish prometheus compatible metrics. Both service specific metrics and basic system metrics like CPU- and memory-usage should be published. The metrics MUST be available on

/api/metrics

Logging

Logging should be done to STDOUT, preferably in JSON format.

Testing

Microservices should have automated unit tests. The tests should be run by Gitlab pipelines on every commit and output results as a JUnit test report.

Linting

Linting should be set up and run by Gitlab pipelines on every commit.

Deploying

Microservices are deployed using Docker containers running in ECS.

Language specific

Javascript - node.js

For backend services written in Javascript and running on node.js please:

• Use roarr for logging

• Use bent for HTTP

• Use jest for testing

• Write unit tests for as much as possible. This will speed up development and debugging a lot compared to manually setting up all the dependent services and APIs and seeding them with proper data.