pattama / cta-restapi

cta-restapi

REST API Modules for Compass Test Automation, One of Libraries in CTA-OSS Framework

General Overview

Guidelines

We aim to give you brief guidelines here.

1. Usage
2. Configuration
3. Providers
4. Provider Implementation

1. Usage

cta-restapi extends Brick (cta-brick). In order to use it, we need to provide a configuration. The cta-restapi depends on cta-expresswrapper.

const config = {
  name: 'restapi',
  module: 'cta-restapi',
  dependencies: {
    express: 'express-tool-name',
  },
  properties: {
    providers: [
      {
        name: 'handlerA',
        module: './utils/restapi/handlers/A.js',
        routes: [
          {
            method: 'post',
            handler: 'create',
            path: '/results',
          },
        ],
      },
      {
        name: 'handlerB',
        module: './utils/restapi/handlers/B.js',
        routes: [
          {
            method: 'post',
            handler: 'create',
            path: '/tasks',
          },
          {
            method: 'get',
            handler: 'alltasks',
            path: '/tasks',
          },
        ],
      },
    ],
  },
};

back to top

2. Configuration

In configuration, there are two requirements.

• cta-restapi requires cta-expresswrapper as dependencies, Dependency on cta-expresswrapper

• cta-restapi requires providers to handle http-actions, Providers on properties

const config = {
  ...
  dependencies: {
    express: 'express-tool-name',
  },
  properties: {
    providers: [ {...}, {...} ]
  },
  ...
};

#Dependency on cta-expresswrapper

In cta-restapi, it requires a name of the tool to run web application, in this case, my-express to dependencies.express.

// configuration file
const config = {
  ...
  dependencies: {
    express: 'my-express',
  },
  ...
};

Then in the other file, the configuration setups a tool using cta-expresswrapper. It setups a tool called "my-express" to match the cta-restapi configuration. Actually, my-express configuration provides port number for Express in cta-expresswrapper.

// ./app/configs/tools/myexpress.js file
const config = {
  tools: [
    {
      name: 'my-express',
      module: 'cta-expresswrapper',
      properties: {
        port: 3000,
      },
    },
  ],
};

#Providers on properties

Another requirement is providers in properties configuration. properties.providers value must be an array of providers.

const config = {
  ...
  properties: {
    providers: [ {...}, {...} ]  // an array of providers
  },
  ...
};

back to top

3. Providers

Providers are handlers to REST path and methods. These are properties of providers.

• name - defines the provider's name

• module - provides the path to provider module

• routes - provides an array of route handlers

  • method - defines REST method type : [ "get", "post", "put", "patch", "delete" ]

  • path - defines REST path

  • handler - defines handler method name of provider

const config = {
  ...
  properties: {
    providers: [{
      name: "sample-provider",
      module: "./util/restapi/sample.provider.js",
      routes: [{
        method: "get",
        path: "/tasks",
        handler: "allTasks",
      }]
    }, {
      ...
    }],
  },
  ...
};

From this configuration, the provider named "sample-provider" is located at "[root]/util/restapi/sample.provider.js". This provider has method called "allTasks()" to handle the REST on path: "GET:: /tasks" (method: get, path: /tasks).

back to top

4. Provider Implementation

Providers Implementation must be a class because cta-restapi instantiate it with new (). cta-restapi provides cementHelper to provider's constructor.

• cta-restapi provides cementHelper to provider's costructor.

// ./util/restapi/sample.provider.js
class SampleProvider {
  constructor(cementHelper) {
    this.cementHelper = cementHelper;
  }
  ...
}

It's strongly recommended to assign cementHelper to instance for use in the class.

#Provider Handlers

The method called "allTasks()" is to handle the REST on path: "GET:: /tasks" (method: get, path: /tasks).

// ./util/restapi/sample.provider.js
class SampleProvider {
  constructor(cementHelper) {
    this.cementHelper = cementHelper;
  }

  allTasks(req, res) {
    const data = {
      nature: {
        type: 'tasks',
        quality: 'getAll',
      },
      payload: req.body,
    };

    const context = this.cementHelper.createContext(data);
    context.on('done', function (brickname, response) {
      res.status(201).send(response);
    });
    context.once('reject', function (brickname, error) {
      res.status(400).send(error.message);
    });
    context.once('error', function (brickname, error) {
      res.status(400).send(error.message);
    });
    context.publish();
  }
}

back to top

---

To Do

---

Considerations

Should we change specific, close-to-'ExpressJS' dependencies.express to a common name, dependencies.[restapp]?

const config = {
  ...
  dependencies: {
    express: 'my-express',  =>  restapp: 'my-express',
  },
  ...
};

---

Should we implement "declaration" instead of "implementation" on providers?

In my opinion, most Providers do two things: 1.) create a payload, 2.) create context and publish it.

I suggest to implement these things as middleware and allow cta-restapi to use middlewares as providers. We will only declare the process in configuration, not have to implement repetitive providers which do the same things over and over. As well, it opens to customizable implementation via middlewares only as it's really needed.

const config = {
  ...
  properties: {
    providers: [{
      name: "sample-provider",
      module: "./util/restapi/sample.provider.js",
      routes: [{
        method: "get",
        path: "/tasks",
        handler: "allTasks",
      }]
    }, {
      name: "declaration-provider",
      use: "restapi-to-payload" // using middleware
      routes: [{
        method: "get",
        path: "/tasks",
        publish: {
          topic: "tasks.service",
          nature: {
            type: "task",
            quality: "getAll",
          }
        }
      }]
    }],
  },
  ...
};

---