README.md

Connected Mobility Solution on AWS - API Module

Connected Mobility Solution on AWS | 🚧 Feature request | 🐛 Bug Report | ❓ General Question

Note: If you want to use the solution without building from source, navigate to the AWS Solution Page.

Table of Contents

• Connected Mobility Solution on AWS - API Module
  • Table of Contents
  • Solution Overview
  • Architecture Diagram
  • Sequence Diagram
  • AWS CDK and Solutions Constructs
  • Customizing the Module
  • Prerequisites
    • MacOS Installation Instructions
    • Clone the Repository
    • Install Required Dependencies
    • Unit Test
    • Build the Module
    • Upload Assets to S3
    • Deploy on AWS
    • Delete
    • GraphQL
    • Authorization
    • Adding GraphQL Operations
    • Generate GraphQL Schema
    • Generate Postman Collection
  • Cost Scaling
  • Collection of Operational Metrics
  • License

Solution Overview

CMS API is a deployable module within Connected Mobility Solution on AWS (CMS) that provides a centralized GraphQL API to serve telemetric data to authorized consumers using AppSync.

For more information and a detailed deployment guide, visit the CMS API Implementation Guide page.

Architecture Diagram

Sequence Diagram

AWS CDK and Solutions Constructs

AWS Cloud Development Kit (AWS CDK) and AWS Solutions Constructs make it easier to consistently create well-architected infrastructure applications. All AWS Solutions Constructs are reviewed by AWS and use best practices established by the AWS Well-Architected Framework.

In addition to the AWS Solutions Constructs, the solution uses AWS CDK directly to create infrastructure resources.

Customizing the Module

Prerequisites

• Python 3.12+
• NVM
• NPM 8+
• Node 18+
• Pipenv

MacOS Installation Instructions

Pyenv Github Repository

brew install pyenv
pyenv install 3.12

Pipenv Github Repository

pip install --user pipenv
pipenv sync --dev

NVM Github Repository

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

NPM/Node Official Documentation

nvm install 18
nvm use 18

Clone the Repository

git clone https://github.com/aws-solutions/connected-mobility-solution-on-aws.git
cd connected-mobility-solution-on-aws/source/modules/cms_api/

Install Required Dependencies

make install

Unit Test

After making changes, run unit tests to make sure added customization passes the tests:

make test

Build the Module

The build script manages dependencies, builds required assets (e.g. packaged lambdas), and creates the AWS Cloudformation templates.

make build

Upload Assets to S3

make upload

Deploy on AWS

make deploy

Delete

make destroy

GraphQL

The CMS API module implements a GraphQL API for serving vehicle data. You can learn more about GraphQL and how to use it here.

Authorization

Users of the API will need to provide a valid bearer token in the Authorization header of each request. This should be an access token obtained from the token endpoint of the configured Identity Provider.

Adding GraphQL Operations

The graphql file containing the available operations is located at ./source/infrastructure/assets/graphql/schemas/vss_operations.graphql. At synthesis time this file and all others located in this directory are bundled into a single graphql schema file named vss_schema.graphql.

To add additional operations the vss_operations.graphql file should be updated with the new query or mutation type. Also, changes should be made to the Athena data source lambda to build and execute the correct Athena query for that operation.

Generate GraphQL Schema

The data models used by CMS are generated by scripts offered by the vss-tools repository. Assets for the default data models are already configured for the solution, however, a user may want to use a different version of the VSS specification or fork the repository and customize the specification to fit their needs. This can be done using the script_generate_models.py script provided:

python ./Connected-mobility-solution-on-aws/deployment/script_generate_models.py

After generating new models, the files must be moved to the appropriate location within the repository and replace the existing models. In CMS API ./source/infrastructure/assets/graphql/schemas/vss_types.graphql must be updated with the newly generated file.

Generate Postman Collection

After deploying the solution a Postman collection can be generated to test and interact with the API.

cd ./deployment/postman_collection
npm ci
node index.js --stack-name <name-of-cloud-formation-stack> --region <region-of-cloud-formation-stack>

A file named cms_graphql_api_postman_collection.json will be generated that can be imported into Postman.

Cost Scaling

Cost will scale on the size of the data the Athena query scans and longer scan times incurring greater lambda costs. At rest, the API's cost is minimal.

• Athena Cost
• AppSync Cost
• AWS Lambda Cost

For more details, see the implementation guide.

Collection of Operational Metrics

This solution collects anonymized operational metrics to help AWS improve the quality and features of the solution. For more information, including how to disable this capability, please see the implementation guide.

License

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.