api/

README

M3O API

The API backend for the M3O Platform.

Overview

This directory serves as the API backend for the M3O platform and related services. These services enable us to offer Micro services as public APIs. The repo includes things like customer management, billing, etc.

Dependencies

We depend on Micro using the "platform" profile. It runs on kubernetes with the resources below:

• Etcd
• Redis
• Postgres

Design

All services are Micro services written using the Micro framework without exception.

• Services speak to each other via RPC
• Messages are used for async eventing
• Infrastructure usage occurs only through Micro

Config

Example config lives in config.json. Fill in the blanks and set micro config set micro "$(cat config.json)"

Events

All events should be defined in protobuf under pkg/events/proto/<topic_name>. The directory should contain the following files.

events.proto

This should define

• enum EventType - enumerates all the event types available
• message Event - which should contain at least the field EnumType type. Any data specific to the event should be defined in separate fields in the Event message. You may also find it useful to have data that is common to all events in a common field. For example, the events on the customers stream have a Customer field which at a minimum contains the customer ID. The events then have event specific messages for any other data, e.g. the field Created contains data associated with the customer creation event.

constants.go

This file should define the topic name so that publishers/consumers can reference this const rather than hand coding the topic name (with the potential for errors). e.g.

const Topic = "customers"

See existing directories for examples.

Mixpanel

Events are forwarded to Mixpanel for analysis. Due to the way enum types are converted to their string representation we need to redeploy the Mixpanel service every time we add events otherwise they will get incorrectly reported.

Testing

We use https://github.com/maxbrunsfeld/counterfeiter for generating test doubles for our services. These can then be imported in to other tests and used instead of real implementations.

We can then write tests which call the endpoints (contract testing) and verify that they do the right thing by checking call counts on the test doubles.

By convention, we generate fakes in the same directory tree as for the real proto implementation. For example, customers service is defined at customers/proto so the test double is defined in customers/proto/fakes.

Example generate command

counterfeiter -o proto/fakes/fake_usage_service.go proto UsageService