Skip to content

Supported Service Types and Code Templates

Jump to bottom Edit New page
Heina Chang edited this page Mar 1, 2019 · 1 revision

Overview

Developing an API (Service type - API)

Defining the API specification

Developing an API starts with defining an API specification using swagger. The default template provides a working sample of a swagger specification to start with, defining few basic model definitions, mappings required for handling success and failure scenarios, request/response mappings, CORS header definitions for allowing cross-site origin calls etc. Swagger specification can be developed in JSON/YAML; Jazz template comes with a JSON version. A sample version of the specification is available in swagger folder.

Click here for a sample version of swagger specification that comes with the template.

Developers can modify their swagger files using swagger editor. You can load the swagger specification file by copy pasting the file content or import from a url into this editor.

Read more about swagger specification here.

Template swagger specification that Jazz provides contains few place holders (that you can ignore during your spec development) but the final version gets auto generated and gets updated based on the deployment environment during the build & deploy process. You will see following placeholder values which are usually replaced during the build process.

  • {api_deployment_node_title} - Title field in swagger that will be replaced with service name by default from the deployment configurations file. You are free to override it.

  • {api_host_name} - The host field which is the endpoint where the API will be published. Each environment has different endpoint provided. This will be auto populated during the build/deployment phase.

  • {domain} – This will be replaced with domain name from the deployment configuration file. Do not modify it.

  • {service_name} – This will be replaced with service name from the deployment configuration file. Do not modify it.

  • {lambda_function_name} – The uri field which has the name of the lambda function being deployed. This will be auto populated during the deployment workflow.

Deployment Configurations

The deployment configurations are stored in the deployment-env.yml file. This file contains metadata related to the service. Developers can use this configuration file to override few configurations (like memory assigned to the function).

  • service_id – Service ID. Do not override this!
  • providerMemorySize – Memory size that you can allocate to your API (underlying function).
  • providerTimeout – Timeout after which function errors out.
  • region – Region where the API will be deployed.
  • iamRoleARN - IAM role that your function should assume. By default, Jazz assigns a role with bare minimum permissions. If your service needs to access other AWS services (like AWS DynamoDB, AWS KMS etc.), you have to create a custom IAM role with the desired permissions and provide the ARN here.
  • artifact – (Specific to java) Should be same as the artifact name given in the maven config file - pom.xml.
  • mainClass – (Specific to java) Should be the name of the main Handler class.

Test Driven Development (TDD)

Templates for both API and Function service types come with sample unit test cases (available in the test folder) to enable TDD. Developers should extend it and add more unit test cases based on their specific business scenarios. NodeJs uses mocha with chai as the unit testing framework. Java uses JUnit and python uses pytest in Jazz environments.

All unit test cases will be run during build process and build workflow aborts when there are failed test cases. Build logs (Jenkins) should provide more details on failed test cases.

Code Analysis and Validations

Basic sanity checks and configuration validations happen during the CI/CD workflow. deployment-env.yml file will be checked for invalid deployment configurations and swagger.json for swagger errors. Workflow fails if there are any errors. You can use swagger editor to validate your swagger.

Based on the runtime, Jazz uses different tools for code analysis. JSHint (ESLint coming soon), PEP 8, checkstyle will be used for NodeJs, Python & Java respectively.

Application Logging

Jazz templates come with logger utilities that does custom logging so that the platform captures logs correctly and pushes them to log management solutions like ElasticSearch or Splunk. AWS APIGateway and AWS Lambda functions write these logs to AWS CloudWatch service which are then pushed to Jazz managed ElasticSearch service (or Splunk if enabled). Java templates use Log4j, NodeJs and Python services use custom loggers in the templates. All templates follow common logging format for Jazz to parse and push them to the managed log engine.

Log format: {TIMESTAMP} {REQUEST_ID} {LOG_LEVEL} {CLASS/FUNCTION:LINE NUMBER} {LOG_MESSAGE}

Example: 2017-04-07T00:01:39 5faf8e67-1b25-11e7-80c2-05b982578e1a INFO RequestHandler:31 Hello! you have logged this message

Developing a Function (Service type - Function)

Services of type function have the same build/deployment process and template structure similar to API services except for the swagger specification. All other configurations and process explained above will be applicable for this service type as well.

After successful deployment, Jazz UI will display the endpoint (ARN) of the function (lambda) under each environment.

Developing Static Websites (Service type – Website)

Jazz provides a simple template when developers create Static Websites. Developers need to (git) push the static content into a folder in the template. Jazz takes care of uploading this static content to an S3 bucket, configure CloudFront distribution (if user opts in) and updates other applicable configurations. The static website template contains these two files/folders -

  • deployment-env.yml contains service_id and few other configuration values that Jazz might need during deployment.
  • app folder contains static content - html, css, js, images, fonts etc. This folder should contain index.html file that would be the home page of your website.

After successful deployment, Jazz UI will display the endpoint (Cloudfront) for the service under each environment.

Self-service create manage serverless services

Add a custom sidebar
Clone this wiki locally