# B.AwsWebsocketApi
An AWS CDK based python library that helps you to create websocket based APIs.
### Description
Creating APIs in AWS is pretty challenging. You have to create stages, deployments,
apis, resources, methods, etc. One might argue that creating a websocket based
API is even harder. This AWS CDK based python library tries to solve this
inconvenience by offering resources and examples on how to create a websocket
API the correct way. We have spent countless hours to perfect it but still
there will always be some "gotchas" in AWS environment.
### Remarks
[Biomapas](https://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
- Python 3
- AWS CDK
- AWS CloudFormation
- AWS API Gateway
- Websockets
### Assumptions
The project assumes the following:
- You have basic-good knowledge in python programming.
- You have basic-good knowledge in AWS.
- You have basic knowledge in websockets.
### Useful sources
- Read more about AWS API Gateway:<br>
https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html.
- Read more about AWS websocket API:<br>
https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-overview.html
### Install
The project is built and uploaded to PyPi. Install it by using pip.
```
pip install b-aws-websocket-api
```
Or directly install it through source.
```
pip install .
```
### Usage & Examples
Create a stack to hold your resources:
```python
from aws_cdk.core import Stack
stack = Stack(...)
```
Create an API:
```python
from b_aws_websocket_api.ws_api import WsApi
api = WsApi(
scope=stack,
id='TestWsApi',
description='Test description.',
name='TestWsApi',
route_selection_expression='$request.body.action',
)
```
Create a stage (usually it is called `prod`):
```python
from b_aws_websocket_api.ws_stage import WsStage
stage = WsStage(
scope=stack,
id='TestStage',
ws_api=api,
stage_name='prod',
auto_deploy=True,
)
```
Create a lambda function to handle incoming requests (frames):
```python
from b_aws_websocket_api.ws_function import WsFunction
from aws_cdk.aws_lambda import Code, Runtime
backend = WsFunction(
scope=stack,
id='TestFunction',
function_name='TestFunction',
code=Code.from_inline(
'def handler(*args, **kwargs):\n'
' return {\n'
' "isBase64Encoded": False,\n'
' "statusCode": 200,\n'
' "headers": {},\n'
' "body": "{\\"message\\": \\"success\\"}"\n'
' }\n'
),
handler='index.handler',
runtime=Runtime.PYTHON_3_6,
)
```
Create a lambda integration (later will be needed for a route):
```python
from b_aws_websocket_api.ws_lambda_integration import WsLambdaIntegration
integration = WsLambdaIntegration(
scope=stack,
id='TestIntegration',
integration_name='TestIntegration',
ws_api=api,
function=backend
)
```
Create a custom route backed by a lambda function:
```python
from b_aws_websocket_api.ws_route import WsRoute
route = WsRoute(
scope=stack,
id='TestRoute',
ws_api=api,
route_key='test',
authorization_type='NONE',
route_response_selection_expression='$default',
target=f'integrations/{integration.ref}',
)
```
Finally deploy the API:
```python
from b_aws_websocket_api.ws_deployment import WsDeployment
deployment = WsDeployment(
scope=stack,
id='TestDeployment',
ws_stage=stage
)
```
And don't forget to solve dependencies for the resources!
```python
deployment.node.add_dependency(route)
deployment.node.add_dependency(stage)
```
Now execute `cdk deploy *` and enjoy your new websocket API!
### Testing
The project has tests that can be run.
Note, that tests are integration tests inherently because they
test how resources are created in AWS environment. Since resources
are created and tested in AWS you are subject for all the applicable
charges while tests are being run.
#### Setting environment
Before running tests set environment variables:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_DEFAULT_REGION
Or:
- AWS_PROFILE
- AWS_DEFAULT_REGION
#### Running tests
Then run tests from a root directory with `pytest` python testing library:
```
pytest b_aws_websocket_api_test
```
Note that integration tests usually take a while to complete (from 5 to 30
minutes on average).
### Contribution
Found a bug? Want to add or suggest a new feature?<br>
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
### 2.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.
### 1.1.0
* Add previously removed websocket http url.
### 1.0.0
* Change ws connections endpoint url and arn function names.
### 0.0.12
* Expose function in lambda integration.
### 0.0.11
* Update docker image for pipelines.
* Add hash properties.
* Make ws deployment more custom.
* Update tests.
### 0.0.9
* Update readme documentation regarding testing.
### 0.0.8
* Add CI/CD pipelines.
* Update History file.
* Refactor testing.
* Update Readme file.
### 0.0.7
* Fix stage log group name.
### 0.0.6
* Move imports in testing manager.
### 0.0.5
* Fix readme.
### 0.0.4
* Update name.
### 0.0.3
* Remove idea files.
### 0.0.2
* Added project files. Added tests.
### 0.0.1
* Initial build. No project files, just a semi-empty project.
Raw data
{
"_id": null,
"home_page": "https://github.com/Biomapas/B.AwsWebsocketApi.git",
"name": "b-aws-websocket-api",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "AWS CDK API WebSocket",
"author": "Laimonas Sutkus",
"author_email": "laimonas.sutkus@biomapas.com",
"download_url": "https://files.pythonhosted.org/packages/08/d2/9bc765d48414a952e69ce6ccc334801350f763528d14508816b5eb9eeb03/b_aws_websocket_api-2.0.0.tar.gz",
"platform": null,
"description": "# B.AwsWebsocketApi\n\nAn AWS CDK based python library that helps you to create websocket based APIs.\n\n### Description\n\nCreating APIs in AWS is pretty challenging. You have to create stages, deployments,\napis, resources, methods, etc. One might argue that creating a websocket based\nAPI is even harder. This AWS CDK based python library tries to solve this \ninconvenience by offering resources and examples on how to create a websocket\nAPI the correct way. We have spent countless hours to perfect it but still\nthere will always be some \"gotchas\" in AWS environment.\n\n### Remarks\n\n[Biomapas](https://biomapas.com) aims to modernise life-science \nindustry by sharing its IT knowledge with other companies and \nthe community. This is an open source library intended to be used \nby anyone. Improvements and pull requests are welcome.\n\n### Related technology\n\n- Python 3\n- AWS CDK\n- AWS CloudFormation\n- AWS API Gateway\n- Websockets\n\n### Assumptions\n\nThe project assumes the following:\n\n- You have basic-good knowledge in python programming.\n- You have basic-good knowledge in AWS.\n- You have basic knowledge in websockets.\n\n### Useful sources\n\n- Read more about AWS API Gateway:<br>\nhttps://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html.\n\n- Read more about AWS websocket API:<br>\nhttps://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-overview.html\n\n### Install\n\nThe project is built and uploaded to PyPi. Install it by using pip.\n\n```\npip install b-aws-websocket-api\n```\n\nOr directly install it through source.\n\n```\npip install .\n```\n\n### Usage & Examples\n\nCreate a stack to hold your resources:\n\n```python\nfrom aws_cdk.core import Stack\nstack = Stack(...)\n```\n\nCreate an API:\n```python\nfrom b_aws_websocket_api.ws_api import WsApi\napi = WsApi(\n scope=stack,\n id='TestWsApi',\n description='Test description.',\n name='TestWsApi',\n route_selection_expression='$request.body.action',\n)\n```\n\nCreate a stage (usually it is called `prod`):\n```python\nfrom b_aws_websocket_api.ws_stage import WsStage\nstage = WsStage(\n scope=stack,\n id='TestStage',\n ws_api=api,\n stage_name='prod',\n auto_deploy=True,\n)\n```\n\nCreate a lambda function to handle incoming requests (frames):\n```python\nfrom b_aws_websocket_api.ws_function import WsFunction\nfrom aws_cdk.aws_lambda import Code, Runtime\nbackend = WsFunction(\n scope=stack,\n id='TestFunction',\n function_name='TestFunction',\n code=Code.from_inline(\n 'def handler(*args, **kwargs):\\n'\n ' return {\\n'\n ' \"isBase64Encoded\": False,\\n'\n ' \"statusCode\": 200,\\n'\n ' \"headers\": {},\\n'\n ' \"body\": \"{\\\\\"message\\\\\": \\\\\"success\\\\\"}\"\\n'\n ' }\\n'\n ),\n handler='index.handler',\n runtime=Runtime.PYTHON_3_6,\n)\n```\n\nCreate a lambda integration (later will be needed for a route):\n```python\nfrom b_aws_websocket_api.ws_lambda_integration import WsLambdaIntegration\nintegration = WsLambdaIntegration(\n scope=stack,\n id='TestIntegration',\n integration_name='TestIntegration',\n ws_api=api,\n function=backend\n)\n```\n\nCreate a custom route backed by a lambda function:\n```python\nfrom b_aws_websocket_api.ws_route import WsRoute\nroute = WsRoute(\n scope=stack,\n id='TestRoute',\n ws_api=api,\n route_key='test',\n authorization_type='NONE',\n route_response_selection_expression='$default',\n target=f'integrations/{integration.ref}',\n)\n```\n\nFinally deploy the API:\n```python\nfrom b_aws_websocket_api.ws_deployment import WsDeployment\ndeployment = WsDeployment(\n scope=stack,\n id='TestDeployment',\n ws_stage=stage\n)\n```\n\nAnd don't forget to solve dependencies for the resources!\n```python\ndeployment.node.add_dependency(route)\ndeployment.node.add_dependency(stage)\n```\n\nNow execute `cdk deploy *` and enjoy your new websocket API!\n\n### Testing\n\nThe project has tests that can be run. \nNote, that tests are integration tests inherently because they\ntest how resources are created in AWS environment. Since resources \nare created and tested in AWS you are subject for all the applicable\ncharges while tests are being run.\n\n#### Setting environment\n\nBefore running tests set environment variables:\n- AWS_ACCESS_KEY_ID\n- AWS_SECRET_ACCESS_KEY\n- AWS_DEFAULT_REGION\n\nOr:\n- AWS_PROFILE\n- AWS_DEFAULT_REGION\n\n#### Running tests\n\nThen run tests from a root directory with `pytest` python testing library:\n```\npytest b_aws_websocket_api_test\n```\n\nNote that integration tests usually take a while to complete (from 5 to 30\nminutes on average).\n\n### Contribution\n\nFound a bug? Want to add or suggest a new feature?<br>\nContributions of any kind are gladly welcome. You may contact us \ndirectly, create a pull-request or an issue in github platform.\nLets modernize the world together.\n\n\n# Release history\n\n### 2.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### 1.1.0\n* Add previously removed websocket http url.\n\n### 1.0.0\n* Change ws connections endpoint url and arn function names.\n\n### 0.0.12\n* Expose function in lambda integration.\n\n### 0.0.11\n* Update docker image for pipelines.\n* Add hash properties.\n* Make ws deployment more custom.\n* Update tests.\n\n### 0.0.9\n* Update readme documentation regarding testing.\n\n### 0.0.8\n* Add CI/CD pipelines.\n* Update History file.\n* Refactor testing.\n* Update Readme file.\n\n### 0.0.7\n* Fix stage log group name.\n\n### 0.0.6\n* Move imports in testing manager.\n\n### 0.0.5\n* Fix readme.\n\n### 0.0.4\n* Update name.\n\n### 0.0.3\n* Remove idea files.\n\n### 0.0.2\n* Added project files. Added tests.\n\n### 0.0.1\n* Initial build. No project files, just a semi-empty project.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "AWS CDK package that helps creating web socket APIs.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/Biomapas/B.AwsWebsocketApi.git"
},
"split_keywords": [
"aws",
"cdk",
"api",
"websocket"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e292deccfe6cc33d0051e2a88965b9b9d3409958f4fa24ef66b4650a43d85682",
"md5": "037f23886ff3ce0d56e26dc89ce9bbf7",
"sha256": "210417867d6e9e81e601190aac70b0aaf2c48ad72f47b53fa3cebec7dfe0f889"
},
"downloads": -1,
"filename": "b_aws_websocket_api-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "037f23886ff3ce0d56e26dc89ce9bbf7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18642,
"upload_time": "2023-08-07T14:12:31",
"upload_time_iso_8601": "2023-08-07T14:12:31.991049Z",
"url": "https://files.pythonhosted.org/packages/e2/92/deccfe6cc33d0051e2a88965b9b9d3409958f4fa24ef66b4650a43d85682/b_aws_websocket_api-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "08d29bc765d48414a952e69ce6ccc334801350f763528d14508816b5eb9eeb03",
"md5": "3dd2221aa6ed6a2c45f116239ca07779",
"sha256": "650883dfe0ca76fdf1cafef1a81012566a45172af6eb9b8db45b2b814e882e0e"
},
"downloads": -1,
"filename": "b_aws_websocket_api-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3dd2221aa6ed6a2c45f116239ca07779",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16808,
"upload_time": "2023-08-07T14:12:32",
"upload_time_iso_8601": "2023-08-07T14:12:32.976481Z",
"url": "https://files.pythonhosted.org/packages/08/d2/9bc765d48414a952e69ce6ccc334801350f763528d14508816b5eb9eeb03/b_aws_websocket_api-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-07 14:12:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Biomapas",
"github_project": "B.AwsWebsocketApi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "b-aws-websocket-api"
}
JSON
