custom_service.md

Custom Service

A Custom Microservice is a service that receives HTTP requests, whose cycle of use and deploy is managed by the platform. A Custom Microservice encapsulates ad-hoc business logics that can be developed by any user of the platform. To know how manage your services in the DevOps Console see the documentation

The library exports a function which creates the infrastructure ready to accept the definition of routes and decorators.
The function optionally can take a schema of the required environment variables (you can find the reference fastify-env.

Example

const customService = require('@mia-platform/custom-plugin-lib')({
  type: 'object',
  required: ['ENV_VAR'],
  properties: {
    ENV_VAR: { type: 'string' },
  },
})

More examples? Go here to see another use cases.

You can configure the environment variables from DevOps console, in your service configuration. For further detail see Mia-Platform documentation.

The customService function expects two arguments:

• an async function to initialize and configure the service, a Fastify instance;
• an optional serviceOptions object useful for configuring the plugins used by the library.

You can access the environment variables values from service.config:

module.exports = customService(async function handler(service) {
  const { ENV_VAR } = service.config
  ...
}, serviceOptions)

Upon service, you can you can add routes and decorators.

The serviceOptions argument supports the following properties:

• ajv: an object useful to customize certain configurations of the ajv instance used by the service:
  • vocabulary: a list of strings used to setup a custom keyword vocabulary,
    keep in mind that if you whish to extend the OAS specification generated by your services and create a valid API specification, each vocabulary entry must start with the x- prefix, check out the OAS specification for further details;
  • plugins: allows setting up the different plugins used by the service:
    • ajv-formats (^2.1.1): with this option you can configure certain ajv-formats configurations
      • formats: a list of strings used to setup the formats that should be allowed when validating schemas

An example of service options is the following:

const serviceOptions = {
  ajv: {
    plugins: {
      'ajv-formats': { formats: ['date-time'] },
    },
    vocabulary: ['x-name'],
  },
}
module.exports = customService(async function myService(service) {
  ...
}, serviceOptions)