Alarm Translation REST API

Table of Contents

• Alarm Translation REST API
  • Table of Contents
  • Getting started
    • Requirements
    • Setting local development
  • Basic usage
  • Test
  • Resources
  • Contributing
    • How does semantic release work

Getting started

Requirements

This project use nodejs, aws-sam-cli and docker, it's required to get them working in your system to run it locally, you can check the following documentation on how to install:

• How to install NodeJS
• How to install SAM CLI
• Get started with docker

Also is necessary to setup NPM Delaval's Registry with:

First we should export the GITLAB_TOKEN variable by doing:

  export GITLAB_TOKEN=<your-personal-gitlab-access-token-with-api-permissions>

Then:

    npm config set '//gitlab.delaval.cloud/api/v4/packages/npm/:_authToken' "${GITLAB_TOKEN}"
    npm config set '//gitlab.delaval.cloud/api/v4/projects/451/packages/npm/:_authToken' "${GITLAB_TOKEN}"
    npm config set @alarm-notification:registry=https://gitlab.delaval.cloud/api/v4/packages/npm/

More information about on How to setup NPM can be found here;

Finally, doing a simple npm install will install all the required project dependencies.

Setting local development

The project relies on AWS SAM and docker to simulate the AWS API Gateway, Lambda and DynamoDB locally. In the package.json file you will find the following npm scripts:

| name | description | |------|--------------| | setup:docker:dynamodb | Starts a new docker container with the DynamoDB local setup | | setup:dynamodb:create | Reads the template.yml file and search for all AWS Resources and creates them locally | | setup:dynamodb:populate | Adds data an initial set of data to DynamoDB |

Run npm run setup:local to start the DynamoDB docker image, create the required DynamoDB tables and fill them with the initial data set. Once DynamoDB is up and running locally, to start the local API Gateway you should run the npm run start:local.

To see more about the DynamoDB resources, check the resources section below.

Basic usage

The Alarm Translation REST API exposes the following endpoint:

• **GET /translations?language=&system= ***

  Returns translation object for a specific system and language. The request requires qs params - language and system - example: GET /translations?language=en&system=alerts will return a json body containing all translations for the chosen system in that language.

  Response

  Response example

  {
      "alarms": {
          "alarmCodes": {
              "777555": {
                  "description": {
                      "text": "test description"
                  }
              },
              "1.1": {
                  "description": {
                      "text": "Robot connected"
                  }
              },
              "1.10": {
                  "description": {
                      "text": "Gate ctrl connected"
                  }
              },
              "1.100": {
                  "description": {
                      "text": "Robot disconnected"
                  }
              },
              "1.101": {
                  "description": {
                      "text": "Milking disconnected"
                  }
              },
          }
      }
  }

Test

The project has unit tests and integration tests that are being run with jest. It's possible to run all the unit test with npm test and the integration test should be run with npm run test:integration.

The integration tests are written using frisbyjs.

Resources

Inside the resources/ folder you will find all files related to AWS resources and the DynamoDB docker-compose configuration file. The resources/create.js script will read the AWS SAM template from the project root, grab all the Resources and create them one by one using the types factories defined in resources/types-factory folder.

Both scripts (create and populate) use a special aws-sdk implementation that will help us to override any AWS Service endpoint by setting the AWS_${service}_ENDPOINT environmental variable. For example, to use our local DynamoDB: AWS_DYNAMODB_ENDPOINT=http://localhost:8000 node resources/create.

Contributing

This project has been configured with three GitHub hooks:

• pre-commit: This hook will run the linters with the --fix and/or --write option to avoid commits with linter errors.
• pre-push: This hook will run all the unit test before doing a git push. If one of the tests fails, It won't let you push to the remote.
• commit message: This hook will analyse your current git commit message with commitlint and force you to follow the conventional commits specification.

Also, it is configured to follow a fully automated version management with semantic-release. Read below for a simple how it works.

How does semantic release work

semantic-release uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog, and publishes the release.

Here is an example of the release type that will be done based on commit messages:

| Commit message | Release type | |---------------|--------------| | fix: stop graphite breaking when too much pressure applied| Patch Release | | feat: add 'graphiteWidth' option | Minor Release | | perf: remove graphiteWidth optionBREAKING CHANGE: The graphiteWidth option has been removed.The default graphite width of 10mm is always used for performance reasons. | Major Release |