Includable microservice base

This repo contains all the basics required to build a microservice for the Includable platform.

Usage

Install using NPM:

npm i @includable/service

Usage information can be found in the example.

Guidelines

Adapters

Only ever enable the adapters that you need, since almost every adapter slows down the startup time of the app, as well as adding dependencies for the app to stay online (database connections etc.)

Currently, the following adapters are available:

• mysql (using Sequelize)
• redis
• queue (using Kue)

REST

All endpoints should use REST HTTP method keywords GET, POST, PUT and DELETE.

Endpoints should always start with their model name in plural:

GET /certificates 			Get all certificates
POST /certificates			Add a certificate
GET /certificates/:id		Get single certificate
DELETE /certificates/:id	Delete certificate

Any IDs or unique identifiers should be formed as UUIDs. When UUIDs have to be generated, always use UUIDv4.

Service independence

Services should be as decoupled from the rest of the platform as possible. That also means avoiding using Includable-specific terms like 'community' or 'reseller' and avoiding directly linking data entries in the database of the server to those types of global entities. Instead, it is a good practice to give every model a field userData, where the consumer of the service can freely add any additional data that they require to later identify to which reseller, community or user a certain entry belongs.

You can set up such a field in a Sequelize model using the following configuration:

userData: {
  type: Sequelize.TEXT,
  allowNull: true
}

User identification

The only exception to that is the notion of a user. What that means exactly and how they are identified may differ from service to service, but a default is to use a UUID string as the user identifier.

This value is known in the main database as an attribute of the user model:

$user = User::find(40);

echo $user->attr('uuid');

In the future, there will also be a getter function on the User model to get this value more easily, simply using $user->uuid.