api-helper

Example

import apiHelper from '@mimik/api-helper';
or
import { apiSetup, securityLib, getAPIFile, validateSecuritySchemes, extractProperties, setupServerFiles } from '@mimik/api-helper';

• api-helper
  • async
    • ~securityLib(config)
    • ~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) ⇒ Promise
    • ~getAPIFile(apiFilename, correlationId, options) ⇒ Promise
    • ~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options) ⇒ Promise
  • sync
    • ~validateSecuritySchemes(apiDefinition, correlationId) ⇒
    • ~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId) ⇒

api-helper~securityLib(config)

Implement the security flows for the API.

Kind: inner method of api-helper
Category: async
Throws:

• Promise An error is thrown if the initiatilization failed.

This function is used to setup the following security handlers for the API:

• SystemSecurity - used for the system operations, like /system, /onbehalf
• AdminSecurity - used for the admin operations, like /admin,
• UserSecurity - used for the user operations, like /user,
• ApiKeySecurity - used for the API key operations, like /apikey, The security handlers are used to validate the tokens and scopes for the API operations.

Requires: module:@mimik/swagger-helper, module:jsonwebtoken, module:lodash

| Param | Type | Description | | --- | --- | --- | | config | object | Configuration of the service. &fulfil {object} The API file itself. |

api-helper~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) ⇒ Promise

Setup the API to be use for a service

Kind: inner method of api-helper
Returns: Promise - . &fulfil {object} The API file itself.
Category: async
Throws:

• Promise An error is thrown if the initiatilization failed.

The following scheme names are reserved: SystemSecurity, AdminSecurity, UserSecurity, PeerSecurity, ApiKeySecurity. The following security schemes can be defaulted: SystemSecurity, AdminSecurity, UserSecurity, ApiKeySecurity. The secOptions in the options property passed when using init allows the following operations:

• introduce a customer security scheme, in this case secOptions contains: { newSecurityScheme: {function}newSecurityHandler },
• disable a security scheme that is defined in the swagger API, in this case secOptions contains: { securitySchemeToDisable: { {boolean}notEnabled: true } },
• overwite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }. If the secOptions is not present either to introduce, disable or overwrite a security scheme that is present in the swagger API file an error is generated. If the secOptions contains unused security schemes, an error is generated.

The default formats for validation are: date, time, date-time, byte, uuid, uri, email, ipv4, ipv6, semver, ip.

Requires: module:@mimik/response-helper, module:@mimik/sumologic-winston-logger, module:@mimik/swagger-helper, module:ajv-formats, module:fs, module:jsonwebtoken, module:lodash

| Param | Type | Description | | --- | --- | --- | | setup | object | Object containing the apiFilename and the exisiting security schemes in the API definition. | | registeredOperations | object | List of the operation to register for the API. | | securityHandlers | object | List of the security handlers to add for the service. | | extraFormats | object | list of the formats to add for validatng properties. | | config | object | Configuration of the service. | | correlationId | UUID.<string> | CorrelationId when logging activites. |

api-helper~getAPIFile(apiFilename, correlationId, options) ⇒ Promise

Gets the API file from swaggerhub and store it in the give PATH location.

Kind: inner method of api-helper
Returns: Promise - . &fulfil {object} The API file itself.
Category: async
Throws:

• Promise An error is thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file connot be saved.

apiInfo options has the following format:

{
   "provider": "provider of the api file, can be `swaggerhub` or `bitbucket`",
   "apiBasicAuth": {
     "username": "username for bitbucket",
     "password": "password for bitbucket"
   },
   "apiApiKey": "apiKey for access private API on swaggerhub, can be optional if the API is accessible publically"
}

**Requires**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  

| Param | Type | Description |
| --- | --- | --- |
| apiFilename | <code>PATH.&lt;string&gt;</code> | Name of the file where the API file will be stored. |
| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiInfo` to access the api file in the api provider. |

<a name="module_api-helper..setupServerFiles"></a>

### api-helper~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options) ⇒ <code>Promise</code>
Setup and validates files for the server

**Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
**Returns**: <code>Promise</code> - .
&fulfil {object} The API file, the API filename, the existing known security schemes and the defined security schemes.  
**Category**: async  
**Throws**:

- <code>Promise</code> An error is thrown for many reasons assocated with getAPIFile or validateSecuritySchemes or extractProperties.

**Requires**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  

| Param | Type | Description |
| --- | --- | --- |
| apiFilename | <code>PATH.&lt;string&gt;</code> | Name of the file where the API file will be stored. |
| controllersDirectory | <code>PATH.&lt;string&gt;</code> | Directory to find the controller files. |
| buildDirectory | <code>PATH.&lt;string&gt;</code> | Directory where the register file will be stored. |
| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API. |

<a name="module_api-helper..validateSecuritySchemes"></a>

### api-helper~validateSecuritySchemes(apiDefinition, correlationId) ⇒
Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.

**Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
**Returns**: An array of the known securitySchemes that are in the API definition.  
**Category**: sync  
**Throws**:

- An error is thrown for the first validation fails.

**Requires**: <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/response-helper</code>  

| Param | Type | Description |
| --- | --- | --- |
| apiDefinition | <code>object</code> | JSON object containing the API definition. |
| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |

<a name="module_api-helper..extractProperties"></a>

### api-helper~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId) ⇒
Extracts the properties from API definiton and creates a file binding the handler with the controller operations.

**Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
**Returns**: null  
**Category**: sync  
**Throws**:

- An error is thrown for many reasons, like operationId does not exist in controllers, controller dies not exist...

**Requires**: <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>  

| Param | Type | Description |
| --- | --- | --- |
| apiDefinition | <code>object</code> | JSON object containing the API definition. |
| controllersDirectory | <code>PATH.&lt;string&gt;</code> | Directory to find the controller files. |
| buildDirectory | <code>PATH.&lt;string&gt;</code> | Directory where the register file will be stored. |
| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |