Promise.<object>
* [~getAPIFile(apiFilename, correlationId, options)](#module_api-helper..getAPIFile) ⇒ Promise.<object>
* [~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options)](#module_api-helper..setupServerFiles) ⇒ Promise.<object>
* _sync_
* [~securityLib(config)](#module_api-helper..securityLib) ⇒ object
* [~validateSecuritySchemes(apiDefinition, correlationId)](#module_api-helper..validateSecuritySchemes) ⇒ Array.<string>
* [~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId)](#module_api-helper..extractProperties) ⇒ void
### api-helper~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) ⇒ Promise.<object>
Set up the API to be used for a service.
**Kind**: inner method of [api-helper](#module_api-helper)
**Returns**: Promise.<object> - The initialized OpenAPIBackend instance.
**Category**: async
**Throws**:
- Error Rejects with an error if the initialization failed.
The following scheme names are reserved: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
The following security schemes can be defaulted: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `ApiKeySecurity`.
The `securityHandlers` parameter maps a security scheme name to a mode-keyed handler object and allows the following operations:
- introduce a custom security scheme, in this case the entry contains: { mySecurityScheme: { regular: {function}newSecurityHandler, mock: {function}newSecurityHandler } },
- disable a security scheme that is defined in the swagger API, in this case the entry contains: { mySecurityScheme: { notEnabled: true } },
- overwrite an existing default security scheme, in this case the entry contains: { SystemSecurity: { regular: {function}newSecurityHandler, mock: {function}newSecurityHandler } }.
The handler used at runtime is selected by mode: `regular` when security is enabled, `mock` when it is disabled. A bare function (not wrapped in `{ regular, mock }`) is silently skipped.
If a security scheme defined in the swagger API file has neither a default handler nor an entry in `securityHandlers`, an error is generated.
If `securityHandlers` contains entries for security schemes that are not defined in the swagger API file, 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:openapi-backend
| Param | Type | Description |
| --- | --- | --- |
| setup | object | Object containing the apiFilename and the existing security schemes in the API definition. |
| setup.apiFilename | [PATH](#PATH) | Path to the resolved API definition file. |
| setup.existingSecuritySchemes | Array.<string> | Known security scheme names present in the API definition. |
| setup.definedSecuritySchemes | Array.<string> | All security scheme names defined in the API definition. |
| registeredOperations | object | Map of operationId to handler function to register for the API. |
| securityHandlers | object | Map of security scheme name to handler object to add for the service. |
| extraFormats | object | Map of format name to format definition for validating properties. Each entry is either an empty object (to use a built-in ajv-formats format) or an object with `type` and `validate` properties (to define a custom format). |
| config | object | Configuration of the service. |
| correlationId | [UUID](#UUID) | CorrelationId when logging activities. |
### api-helper~getAPIFile(apiFilename, correlationId, options) ⇒ Promise.<object>
Gets and resolves the API definition, loading from local file, Bitbucket, or SwaggerHub, and stores it in the given PATH location.
**Kind**: inner method of [api-helper](#module_api-helper)
**Returns**: Promise.<object> - The API file itself.
**Category**: async
**Throws**:
- Error Rejects with an error if the apiFilename resolution generates an error or the request to the API provider fails or the file cannot be saved.
`apiInfo` options has the following format:
``` javascript
{
"provider": "provider of the api file, can be `swaggerhub` or `bitbucket`",
"apiBasicAuth": {
"username": "username for bitbucket",
"password": "password for bitbucket"
},
"apiApiKey": "apiKey to access private API on swaggerhub, can be optional if the API is accessible publicly"
}
```
**Requires**: module:@mimik/request-retry, module:@mimik/response-helper, module:@mimik/sumologic-winston-logger, module:fs, module:js-yaml, module:path
| Param | Type | Description |
| --- | --- | --- |
| apiFilename | [PATH](#PATH) | Name of the file where the API file will be stored. |
| correlationId | [UUID](#UUID) | CorrelationId when logging activities. |
| options | object | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiInfo` to access the api file in the api provider. |
### api-helper~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options) ⇒ Promise.<object>
Sets up and validates files for the server.
**Kind**: inner method of [api-helper](#module_api-helper)
**Returns**: Promise.<object> - The API file, the API filename, the existing known security schemes and the defined security schemes.
**Category**: async
**Throws**:
- Error Rejects with an error for many reasons associated with getAPIFile or validateSecuritySchemes or extractProperties.
**Requires**: module:@mimik/request-retry, module:@mimik/response-helper, module:@mimik/sumologic-winston-logger, module:fs, module:js-yaml, module:path
| Param | Type | Description |
| --- | --- | --- |
| apiFilename | [PATH](#PATH) | Name of the file where the API file will be stored. |
| controllersDirectory | [PATH](#PATH) | Directory to find the controller files. |
| buildDirectory | [PATH](#PATH) | Directory where the register file will be stored. |
| correlationId | [UUID](#UUID) | CorrelationId when logging activities. |
| options | object | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiInfo` to access the api file in the api provider. |
### api-helper~securityLib(config) ⇒ object
Implements the security flows for the API.
**Kind**: inner method of [api-helper](#module_api-helper)
**Returns**: object - An object containing `SystemSecurity`, `AdminSecurity`, `UserSecurity`, and `ApiKeySecurity` handlers.
This function is used to set up the following security handlers for the API:
- `SystemSecurity` - used for system-to-system operations, validates client credentials tokens.
- `AdminSecurity` - used for admin operations, validates admin/subAdmin client credentials tokens.
- `UserSecurity` - used for user operations, validates implicit flow tokens.
- `ApiKeySecurity` - used for API key authenticated operations, validates API keys from headers.
The security handlers are used to validate the tokens and scopes for the API operations.
**Category**: sync
**Requires**: module:@mimik/swagger-helper, module:jsonwebtoken
| Param | Type | Description |
| --- | --- | --- |
| config | object | Configuration of the service. |
### api-helper~validateSecuritySchemes(apiDefinition, correlationId) ⇒ Array.<string>
Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
**Kind**: inner method of [api-helper](#module_api-helper)
**Returns**: Array.<string> - An array of the known securitySchemes that are in the API definition.
**Category**: sync
**Throws**:
- Error An error is thrown if a validation fails.
**Requires**: module:@mimik/sumologic-winston-logger, module:@mimik/response-helper
| Param | Type | Description |
| --- | --- | --- |
| apiDefinition | object | JSON object containing the API definition. |
| correlationId | [UUID](#UUID) | CorrelationId when logging activities. |
### api-helper~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId) ⇒ void
Extracts the properties from API definition and creates a `register.js` file in the build directory binding the handler with the controller operations.
**Kind**: inner method of [api-helper](#module_api-helper)
**Category**: sync
**Throws**:
- Error An error is thrown for many reasons, like operationId does not exist in controllers, controller does not exist...
**Requires**: module:@mimik/response-helper, module:@mimik/sumologic-winston-logger, module:fs
| Param | Type | Description |
| --- | --- | --- |
| apiDefinition | object | JSON object containing the API definition. |
| controllersDirectory | [PATH](#PATH) | Directory to find the controller files. |
| buildDirectory | [PATH](#PATH) | Directory where the register file will be stored. |
| correlationId | [UUID](#UUID) | CorrelationId when logging activities. |
## UUID : string
UUID string in RFC 4122 format.
**Kind**: global typedef
## PATH : string
File system path string.
**Kind**: global typedef
---
_Source: https://npm.io/package/@mimik/api-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._