# B.CfnApiV2
An API Gateway resource that adds convenient functionality over traditional `CfnApi` resource.
It lets you easily enable authorization, stages, and CDNs.
### Description
Essentially this resource is a wrapper resource for `aws_apigatewayv2` module's `CfnApi`. Meaning,
that you can easily swap `CfnApi` and this `Api` resource with no major impact. But why would you
want to switch a traditional `CfnApi` to this one. Mainly these convenient features:
- Easy to add `CloudFront` distribution on top of the API (enabling CDN).
- Easy to enable `Stage` and attached to the api.
- Easy to add authorization with `UserPoolAuthorizer` & `ApiKeyAuthorizer`.
### Remarks
[Biomapas](https://www.biomapas.com/) aims to modernise life-science industry by sharing its IT knowledge with other companies and the community.
This is an open source library intended to be used by anyone.
Improvements and pull requests are welcome.
### Related technology
- Python3
- AWS CDK
- AWS Lambda
- AWS API Gateway
- AWS CloudFront
- AWS User Pool authorization
### Assumptions
This project assumes you know what Lambda functions are and how code is being shared between them
(Lambda layers).
- Excellent knowledge in IaaC (Infrastructure as a Code) principles.
- Excellent knowledge in Lambda functions and API Gateway service.
- Good experience in AWS CDK and AWS CloudFormation.
### Useful sources
- AWS CDK:<br>https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html
- AWS CloudFormation:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html
- AWS API Gateway:<br>https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html
- AWS API Gateway V2:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html
- Custom User Pool Authorizer:<br>https://github.com/Biomapas/B.CfnCustomUserPoolAuthorizer
- Custom api key authorizer:<br>https://github.com/Biomapas/B.CfnCustomApiKeyAuthorizer
- Custom user pool authorizer:<br>https://github.com/Biomapas/B.CfnCustomUserPoolAuthorizer
### Install
Before installing this library, ensure you have these tools setup:
- Python / Pip
- AWS CDK
To install this project from source run:
```
pip install .
```
Or you can install it from a PyPi repository:
```
pip install b-cfn-api-v2
```
### Usage & Examples
The traditional way of creating an API looks something like this:
```python
from aws_cdk.aws_apigatewayv2 import CfnApi
CfnApi(
scope=Stack(),
id='Api',
name='Api',
description='Sample description.',
protocol_type='HTTP',
cors_configuration=CfnApi.CorsProperty(
allow_methods=['GET', 'PUT', 'POST', 'OPTIONS', 'DELETE'],
allow_origins=['*'],
allow_headers=[
'Content-Type',
'Authorization'
],
max_age=300
)
)
```
To create our resource `Api` is exactly the same:<br>
(It works since `Api` is a pure wrapper of `CfnApi` resource.)
```python
from b_cfn_api_v2.api import Api
Api(
scope=Stack(),
id='Api',
name='Api',
description='Sample description.',
protocol_type='HTTP',
cors_configuration=Api.CorsProperty(
allow_methods=['GET', 'PUT', 'POST', 'OPTIONS', 'DELETE'],
allow_origins=['*'],
allow_headers=[
'Content-Type',
'Authorization'
],
max_age=300
)
)
```
Three main advantages of this `Api` resource:
- **Easy to enable default stage.**
```python
from b_cfn_api_v2.api import Api
api = Api(...)
api.enable_default_stage('dev')
```
- **Easy to enable authorization.**
```python
from b_cfn_api_v2.api import Api
from b_cfn_custom_userpool_authorizer.config.user_pool_config import UserPoolConfig
api = Api(...)
# Your authorized endpoint will require `Authorization`
# supplied in headers.
# Read more:
# https://github.com/Biomapas/B.CfnCustomUserPoolAuthorizer
api.enable_user_pool_authorizer(UserPoolConfig(
user_pool_id='id',
user_pool_region='region',
user_pool_client_id='client'
))
# Your authorized endpoint will require `ApiKey` and `ApiSecret`
# supplied in headers.
# Read more:
# https://github.com/Biomapas/B.CfnCustomApiKeyAuthorizer
api.enable_api_key_authorizer()
```
- **Easy to enable CDN.**
```python
from b_cfn_api_v2.api import Api
from aws_cdk.aws_cloudfront import CachePolicy
api = Api(...)
api.enable_cdn(default_behavior_cache_policy=CachePolicy.CACHING_OPTIMIZED)
```
### Testing
This package has integration tests based on **pytest**.
To run tests simply run:
```
pytest b_cfn_api_v2_test/integration/tests
```
### Contribution
Found a bug? Want to add or suggest a new feature?
Contributions of any kind are gladly welcome.
You may contact us directly, create a pull-request or an issue in github platform.
Lets modernize the world together.
# Release history
### 5.0.0
* Upgrade CDK support from v1 to v2.
* Upgrade GitHub pipelines checkout version from v2 to v3.
* Set GitHub pipelines node version 18.
* Set GitHub pipelines python version 3.10.
### 4.0.0
* Fix origin paths between pure api or its cloudfront distribution.
Both should require stage name to be entered as a part of a URL.
This is a breaking change.
### 3.1.0
* Enable easy stage logging.
### 3.0.0
* Upgrade breaking dependencies.
### 2.0.1
* Make dependencies range more loose with maximum version not reaching `2.0.0`.
### 2.0.0
* Use the newest `2.0.0` custom api keys authorizer which now hashes
api secrets and is no longer compatible with previous versions.
### 1.1.1
* Update readme.
### 1.1.0
* Implement api keys custom authorizer (https://github.com/Biomapas/B.CfnCustomApiKeyAuthorizer).
### 1.0.0
* Fully documented, tested, and working version release.
### 0.0.1
* Initial build.
Raw data
{
"_id": null,
"home_page": "https://github.com/biomapas/B.CfnApiV2.git",
"name": "b-cfn-api-v2",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "AWS API Gateway",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/da/d4/2509d507f29a1d8db372e97123a4184f3b480691789f486465232d5e8513/b_cfn_api_v2-5.0.0.tar.gz",
"platform": null,
"description": "# B.CfnApiV2\n\n\n\nAn API Gateway resource that adds convenient functionality over traditional `CfnApi` resource. \nIt lets you easily enable authorization, stages, and CDNs. \n\n### Description\n\nEssentially this resource is a wrapper resource for `aws_apigatewayv2` module's `CfnApi`. Meaning, \nthat you can easily swap `CfnApi` and this `Api` resource with no major impact. But why would you \nwant to switch a traditional `CfnApi` to this one. Mainly these convenient features:\n- Easy to add `CloudFront` distribution on top of the API (enabling CDN).\n- Easy to enable `Stage` and attached to the api.\n- Easy to add authorization with `UserPoolAuthorizer` & `ApiKeyAuthorizer`.\n\n### Remarks\n\n[Biomapas](https://www.biomapas.com/) aims to modernise life-science industry by sharing its IT knowledge with other companies and the community. \nThis is an open source library intended to be used by anyone. \nImprovements and pull requests are welcome. \n\n### Related technology\n\n- Python3\n- AWS CDK\n- AWS Lambda\n- AWS API Gateway\n- AWS CloudFront\n- AWS User Pool authorization\n\n### Assumptions\n\nThis project assumes you know what Lambda functions are and how code is being shared between them\n(Lambda layers). \n\n- Excellent knowledge in IaaC (Infrastructure as a Code) principles.\n- Excellent knowledge in Lambda functions and API Gateway service. \n- Good experience in AWS CDK and AWS CloudFormation.\n\n### Useful sources\n\n- AWS CDK:<br>https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html\n- AWS CloudFormation:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html\n- AWS API Gateway:<br>https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html\n- AWS API Gateway V2:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html\n- Custom User Pool Authorizer:<br>https://github.com/Biomapas/B.CfnCustomUserPoolAuthorizer\n- Custom api key authorizer:<br>https://github.com/Biomapas/B.CfnCustomApiKeyAuthorizer\n- Custom user pool authorizer:<br>https://github.com/Biomapas/B.CfnCustomUserPoolAuthorizer\n\n### Install\n\nBefore installing this library, ensure you have these tools setup:\n\n- Python / Pip\n- AWS CDK\n\nTo install this project from source run:\n\n```\npip install .\n```\n\n\nOr you can install it from a PyPi repository:\n\n```\npip install b-cfn-api-v2\n```\n\n\n### Usage & Examples\n\nThe traditional way of creating an API looks something like this:\n\n```python\nfrom aws_cdk.aws_apigatewayv2 import CfnApi\n\nCfnApi(\n scope=Stack(),\n id='Api',\n name='Api',\n description='Sample description.',\n protocol_type='HTTP',\n cors_configuration=CfnApi.CorsProperty(\n allow_methods=['GET', 'PUT', 'POST', 'OPTIONS', 'DELETE'],\n allow_origins=['*'],\n allow_headers=[\n 'Content-Type',\n 'Authorization'\n ],\n max_age=300\n )\n)\n```\n\nTo create our resource `Api` is exactly the same:<br>\n(It works since `Api` is a pure wrapper of `CfnApi` resource.)\n\n```python\nfrom b_cfn_api_v2.api import Api\n\nApi(\n scope=Stack(),\n id='Api',\n name='Api',\n description='Sample description.',\n protocol_type='HTTP',\n cors_configuration=Api.CorsProperty(\n allow_methods=['GET', 'PUT', 'POST', 'OPTIONS', 'DELETE'],\n allow_origins=['*'],\n allow_headers=[\n 'Content-Type',\n 'Authorization'\n ],\n max_age=300\n )\n)\n```\n\nThree main advantages of this `Api` resource:\n\n- **Easy to enable default stage.**\n\n```python\nfrom b_cfn_api_v2.api import Api\n\napi = Api(...)\napi.enable_default_stage('dev')\n```\n\n- **Easy to enable authorization.**\n\n```python\nfrom b_cfn_api_v2.api import Api\nfrom b_cfn_custom_userpool_authorizer.config.user_pool_config import UserPoolConfig\n\napi = Api(...)\n\n# Your authorized endpoint will require `Authorization`\n# supplied in headers.\n# Read more:\n# https://github.com/Biomapas/B.CfnCustomUserPoolAuthorizer\napi.enable_user_pool_authorizer(UserPoolConfig(\n user_pool_id='id',\n user_pool_region='region',\n user_pool_client_id='client'\n))\n\n# Your authorized endpoint will require `ApiKey` and `ApiSecret`\n# supplied in headers.\n# Read more:\n# https://github.com/Biomapas/B.CfnCustomApiKeyAuthorizer\napi.enable_api_key_authorizer()\n```\n\n- **Easy to enable CDN.**\n\n```python\nfrom b_cfn_api_v2.api import Api\nfrom aws_cdk.aws_cloudfront import CachePolicy\n\napi = Api(...)\napi.enable_cdn(default_behavior_cache_policy=CachePolicy.CACHING_OPTIMIZED)\n```\n\n### Testing\n\nThis package has integration tests based on **pytest**.\nTo run tests simply run:\n\n```\npytest b_cfn_api_v2_test/integration/tests\n```\n\n### Contribution\n\nFound a bug? Want to add or suggest a new feature? \nContributions of any kind are gladly welcome. \nYou may contact us directly, create a pull-request or an issue in github platform. \nLets modernize the world together.\n\n\n# Release history\n\n### 5.0.0\n* Upgrade CDK support from v1 to v2.\n* Upgrade GitHub pipelines checkout version from v2 to v3.\n* Set GitHub pipelines node version 18.\n* Set GitHub pipelines python version 3.10.\n\n### 4.0.0\n* Fix origin paths between pure api or its cloudfront distribution.\n Both should require stage name to be entered as a part of a URL.\n This is a breaking change.\n\n### 3.1.0\n* Enable easy stage logging.\n\n### 3.0.0\n* Upgrade breaking dependencies.\n\n### 2.0.1\n* Make dependencies range more loose with maximum version not reaching `2.0.0`.\n\n### 2.0.0\n* Use the newest `2.0.0` custom api keys authorizer which now hashes \napi secrets and is no longer compatible with previous versions. \n\n### 1.1.1\n* Update readme.\n\n### 1.1.0\n* Implement api keys custom authorizer (https://github.com/Biomapas/B.CfnCustomApiKeyAuthorizer).\n\n### 1.0.0\n* Fully documented, tested, and working version release.\n\n### 0.0.1\n* Initial build. \n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Convenient wrapper around CfnApi.",
"version": "5.0.0",
"project_urls": {
"Homepage": "https://github.com/biomapas/B.CfnApiV2.git"
},
"split_keywords": [
"aws",
"api",
"gateway"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d305bbb6fda2b538836372e130d2f3cc0e8f5aadc18d39c0e505d22d0077d185",
"md5": "84584037c3843b7225435968426b39bf",
"sha256": "b6ebe277ec5f03d4ced65ef0823de30e693bfa9791a74682f4f14d90862a34dc"
},
"downloads": -1,
"filename": "b_cfn_api_v2-5.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84584037c3843b7225435968426b39bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22169,
"upload_time": "2023-08-04T08:07:29",
"upload_time_iso_8601": "2023-08-04T08:07:29.880109Z",
"url": "https://files.pythonhosted.org/packages/d3/05/bbb6fda2b538836372e130d2f3cc0e8f5aadc18d39c0e505d22d0077d185/b_cfn_api_v2-5.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dad42509d507f29a1d8db372e97123a4184f3b480691789f486465232d5e8513",
"md5": "1abf70ffdf2e7461f6223edfff94a6f9",
"sha256": "5d73deae8a6811ff3e46f5434594c88a6eb5523b4a27d1cdce08be50efad7400"
},
"downloads": -1,
"filename": "b_cfn_api_v2-5.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1abf70ffdf2e7461f6223edfff94a6f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15661,
"upload_time": "2023-08-04T08:07:31",
"upload_time_iso_8601": "2023-08-04T08:07:31.361429Z",
"url": "https://files.pythonhosted.org/packages/da/d4/2509d507f29a1d8db372e97123a4184f3b480691789f486465232d5e8513/b_cfn_api_v2-5.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-04 08:07:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "biomapas",
"github_project": "B.CfnApiV2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "b-cfn-api-v2"
}
JSON
