npm.io
3.0.6 • Published 2 months ago

@mimik/api-helper

Licence
MIT
Version
3.0.6
Deps
10
Size
55 kB
Vulns
3
Weekly
0
SummaryDependencyVersions

Modules

api-helper

Typedefs

UUID : string

UUID string in RFC 4122 format.

PATH : string

File system path string.

api-helper

Example 

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

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
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 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 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
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:

{
   "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 Name of the file where the API file will be stored.
correlationId 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
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 Name of the file where the API file will be stored.
controllersDirectory PATH Directory to find the controller files.
buildDirectory PATH Directory where the register file will be stored.
correlationId 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
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
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 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
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 Directory to find the controller files.
buildDirectory PATH Directory where the register file will be stored.
correlationId 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

Keywords

mimikmicroserviceopenAPI