Skip to content

Latest commit

 

History

History
218 lines (138 loc) · 9.66 KB

README.md

File metadata and controls

218 lines (138 loc) · 9.66 KB
Raw

GitHub Actions workflows status

Deploy status Build status Docs generation status

CodeClimate

Repository initialization

When creating a repository from this template an init workflow (see here) will run. This workflow uses kaskadi-cli in order to properly initialize your repository by:

  • updating the names refering to the template in relevant files (for example package.json, package-lock.json, etc.) and renaming some files if need be
  • automatically adding your repository to Code Climate
  • automatically setting REPORTER_ID secret inside of your repository for test coverage upload to Code Climate. This may fail because of Code Climate infrastructure latency in setting up your repository. In such case your workflow will emit a warning telling you to set REPORTER_ID manually

Testing

mocha, chai, nyc, serverless-offline & standard are available as dev dependencies.

A build workflow (see here) is running on pull request and will execute your test suite before allowing you to merge your PR. It also has a coverage job already prepared that you can comment out as soon as your testing is in place and your REPORTER_ID is in the repository secrets. This is the ID on Code Climate used for uploading code coverage reports.

Beside running your unit tests, this workflow runs a static code analysis to find any vulnerability in your code. If a vulnerability is found, a notification will appear in the Security tab of your repository.

The build workflow also runs a syntax-check job which checks your serverless.yml file syntax.

Documentation

This repository comes with a generate-docs workflow that generates documentation automatically for you by reading your main serverless.yml configuration file and extracting meta data of all endpoints you defined. See here and there for more information.

Before generating the documentation, the workflow will check for syntax error in your serverless.yml file.

If you would like to see the workflow configuration, head here.

You can configure the template used to generate the action documentation here.

Deploying

Deploying to AWS is done automatically via a deploy workflow (see here). This workflow will run on push. Before publishing it:

  1. performs a static code analysis of the layer to detect any vulnerabilities. If a vulnerability is found, a notification will appear in the Security tab of your repository
  2. checks the syntax of serverless.yml for any errors
  3. run any tests you may have set up with npm test

You'll have to switch the command from --version to deploy -v in the workflow configuration file to actually deploy!

Warning: you may need to manually deploy the first time via Serverless CLI locally.

Tools

Add new endpoints

In order to add new endpoints:

  1. Go to the root of your API repository
  2. Run npm run add-lambda (this will prompt you for new lambda data)
  3. Your endpoint is now located under lambdas/<lambda_name> and you can start developing!

Upgrade API version

To update your API version, run npm run upgrade-version <version_option>. This takes the same argument as npm version (see here). It will update for you the main package.json as well as serverless.json but also all package.json for all endpoints.

Using custom domain for your API

For all custom domains you will need a certificate for this domain. Please make sure that you have the proper certificate generated, else create one associated with your domain. All this can be done here

Case 1: creating a new custom domain for API

If the custom domain you wish to use hasn't been created yet (list of custom domains here).

  1. Go here and click on Create Custom Domain Name
  2. Configure your domain as you wish to
  3. Once the domain is created and initialized, go to Route 53
  4. Go into the Hosted Zone for the domain you wish to use and create a new A Record.
  5. For this record, you should toggle the Alias option, give for name the custom domain name you wish to use and select for Alias target the API you want to map to this domain. You may need to copy paste the base URL to that API to make this work

Case 2: using an existing custom domain

  1. Go here
  2. Click on Edit for the custom domain you wish to use
  3. Add a base path you wish to map your API to for this domain and then select the API & its stage in the dropdown menus

Attention: you can only use an existing custom domain if this domain doesn't have already an empty path as base path.

API endpoints

The origin and root path for this API is: https://api.template.com/logical-unit

The following endpoints are defined in this API:

/hello

Supported methods:

GET (target lambda → hello-world)

Description:

hello world placeholder endpoint

Authorization:

No authorizer found for this method.

Query string parameters:

Key Default Description
key1 first key
key2 35 second key

Request body:

Key Default Description
param1 hello first body param
param2 true second body param

Examples:

Example #1

Request:

GET https://api.template.com/logical-unit/hello?key1=hello&key2=test

Headers:
  Content-Type: application/json

Body:
  {
    "param1": "does not make sense in GET",
    "param2": "but this is a test"
  }

Response:

Status code:
  200

Headers:
  x-kaskadi-data: some data

Body:
  {
    "resParam1": "hello",
    "resParam2": "test"
  }

API resources

The following lambda functions are used in this API:

The following layers are used in this API:

hello-world

Name Sources Timeout Handler Layers
hello-world
  • HTTP (GET)
 default handler

See configuration file for more details.

template-kaskadi-api-layer

Description

Layer for template-kaskadi-api

Dependencies

  • template-kaskadi-api-utils (local utility)

See configuration file for more details.

Stack tags

You can use any tags (and their respective values) visible below to find ressources related to this stack on AWS. See here for more details.

Tag Value
app your-app-name
service template-kaskadi-api
logical-unit api-logical-unit
type s3, sns, etc.