Skip to content

Latest commit

 

History

History
503 lines (332 loc) · 21.8 KB

API.md

File metadata and controls

503 lines (332 loc) · 21.8 KB
Raw

api-gw-reconciler

All Contributors

AWS API gateway reconciler

AWS API gateway reconciler checks and merges openapi schemas from services. Reconciler is cdk library construct, which could be deployed as part of AWS CDK application

📚 Table of Contents

📦 Installation

npm i @affinidi/api-gw-reconciler

🔋 Features

  • Merging openapi schemas from different services in one openapi schema and updating single API gateway
  • Checking for backwards compatibilty of schema
  • schema path authentication for specifc service path prefix
  • Pinning 1 schema to provide authorizers
  • Generates and publishes json api doc
  • Generates and publishes ReDoc HTML documentation
  • Token Auth for documentation

🚀 Usage

For more complex example, take a look into [examples]

//Create API gw somewhere
const api = new apigateway.RestApi(this, 'api')
api.root.addMethod('ANY')

Create reconciler

//Reference apigateway in reconciler stack
const  restApiId = 'fe3sdf4x'
restApiReference = apigateway.RestApi.fromRestApiId(this, 'restApiReference', restApiId)
//Create reconsiler
const reconciler = new APIGWReconciler(this, 'reconciler', {
  restAPI: restApiReference
  allowedAccounts: [
    {
      allowedApiPathPrefix: 'service1',
      id: '1111111111'
    },
    {
      allowedApiPathPrefix: 'service2',
      id: '22222222222'
    },
  ]
})

Upload openapi.json schema in service stack

const oas = {
  "openapi": "3.0.0",
  "paths:" : [...]
  ...
}
new BucketDeployment(this, 'openapiSchemaDeployment', {
    destinationBucket: this.reconciler.openApiDefinitionBucket,
    destinationKeyPrefix: 'service1',
    prune: false,
    sources: [Source.jsonData('openapi.json', oas)],
})

🪚 How it works

Take a look into detailed example

🛠️ Support

Please open an issue for support.

📝 Contributing

Please contribute using Github Flow. Create a branch, add commits, and open a pull request.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

maratsh
maratsh
💻 📖 💡 🤔 🚇 🚧 📦 💬 👀 ⚠️ ✅		 Robert
Robert
👀 💻		 Yiğitcan UÇUM
Yiğitcan UÇUM
🤔 💻		 Stanislav Demchuk
Stanislav Demchuk
👀		 yaroslava-kurash
yaroslava-kurash
💻		 Dmytro Filipenko
Dmytro Filipenko
💻		 Vyatcheslav Mogilevsky
Vyatcheslav Mogilevsky
💻 👀
Raja
Raja
💻		 Anton Iskryzhytskyi
Anton Iskryzhytskyi
💻 🤔 👀		 kwekmh-affinidi
kwekmh-affinidi
👀 🛡️
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

API Reference

Constructs

APIGWReconciler

AWS API GW reconciler.

reconciler merges openapi schemas from services and updates central API gw with result schemas

Initializers 

import { APIGWReconciler } from '@affinidi/api-gw-reconciler'

new APIGWReconciler(scope: Stack, id: string, props: IAPIGWReconcilerProps)
Name Type Description
scope aws-cdk-lib.Stack No description.
id string No description.
props IAPIGWReconcilerProps No description.
scopeRequired
  • Type: aws-cdk-lib.Stack
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { APIGWReconciler } from '@affinidi/api-gw-reconciler'

APIGWReconciler.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
mergedOpenapiBucket aws-cdk-lib.aws_s3.Bucket No description.
openApiDefinitionBucket aws-cdk-lib.aws_s3.Bucket No description.
openapiDocsLambda aws-cdk-lib.aws_lambda_nodejs.NodejsFunction No description.
openapiInfoMetadataKey string No description.
reconcilerLambda aws-cdk-lib.aws_lambda_nodejs.NodejsFunction No description.
redocLambda aws-cdk-lib.aws_lambda_nodejs.NodejsFunction No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

mergedOpenapiBucketRequired 
public readonly mergedOpenapiBucket: Bucket;
  • Type: aws-cdk-lib.aws_s3.Bucket
openApiDefinitionBucketRequired 
public readonly openApiDefinitionBucket: Bucket;
  • Type: aws-cdk-lib.aws_s3.Bucket
openapiDocsLambdaRequired 
public readonly openapiDocsLambda: NodejsFunction;
  • Type: aws-cdk-lib.aws_lambda_nodejs.NodejsFunction
openapiInfoMetadataKeyRequired 
public readonly openapiInfoMetadataKey: string;
  • Type: string
reconcilerLambdaRequired 
public readonly reconcilerLambda: NodejsFunction;
  • Type: aws-cdk-lib.aws_lambda_nodejs.NodejsFunction
redocLambdaRequired 
public readonly redocLambda: NodejsFunction;
  • Type: aws-cdk-lib.aws_lambda_nodejs.NodejsFunction

Structs

OpenAPIDefinitionHeader

Initializer 

import { OpenAPIDefinitionHeader } from '@affinidi/api-gw-reconciler'

const openAPIDefinitionHeader: OpenAPIDefinitionHeader = { ... }

Properties

Name Type Description
info {[ key: string ]: any} No description.
infoRequired 
public readonly info: {[ key: string ]: any};
  • Type: {[ key: string ]: any}

Protocols

IAPIGWReconcilerallowedAccount

aws account id to api path prefix mapping.

Properties

Name Type Description
allowedApiPathPrefix string API path prefix allowed for given account id.
id string Account Id of service under API path prefix.
allowedApiPathPrefixRequired 
public readonly allowedApiPathPrefix: string;
  • Type: string

API path prefix allowed for given account id.

idRequired 
public readonly id: string;
  • Type: string

Account Id of service under API path prefix.

IAPIGWReconcilerProps

Properties

Name Type Description
allowedAccounts IAPIGWReconcilerallowedAccount[] No description.
restAPI aws-cdk-lib.aws_apigateway.IRestApi restAPI managed by reconciler.
apiDocPathPrefix string path prefix for api doc.
apiDocSimpleAuthToken string Simple authentication token to keep your apidoc somewhat private.
openapiHeader OpenAPIDefinitionHeader Default schema, defines title, description, version.
openapiInfoMetadataKey string Key in service openapi schema under info key.
securitySchemaPath string security schema path this schema configures authorizers in API gw.
allowedAccountsRequired 
public readonly allowedAccounts: IAPIGWReconcilerallowedAccount[];
restAPIRequired 
public readonly restAPI: IRestApi;
  • Type: aws-cdk-lib.aws_apigateway.IRestApi

restAPI managed by reconciler.

apiDocPathPrefixOptional 
public readonly apiDocPathPrefix: string;
  • Type: string
  • Default: 'api-docs'

path prefix for api doc.

apiDocSimpleAuthTokenOptional 
public readonly apiDocSimpleAuthToken: string;
  • Type: string
  • Default: ''

Simple authentication token to keep your apidoc somewhat private.

openapiHeaderOptional 
public readonly openapiHeader: OpenAPIDefinitionHeader;

Default schema, defines title, description, version.

openapiInfoMetadataKeyOptional 
public readonly openapiInfoMetadataKey: string;
  • Type: string
  • Default: 'x-reconciler'

Key in service openapi schema under info key.

securitySchemaPathOptional 
public readonly securitySchemaPath: string;
  • Type: string
  • Default: "iam/openapi.json"

security schema path this schema configures authorizers in API gw.