Supported Service Types and Code Templates for Azure

Overview

• Developing an API (Service type - API)
  • Defining the API specification
  • Deployment Configurations
  • Test Driven Development (TDD)
  • Code Analysis and Validations
  • Application Logging
• Developing a Function (Service type - Function)
• Developing a Static Website (Service type – Website)

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.

• {domain} - Title field in swagger that will be replaced with service name. Do not override it.

• {functionName} - 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.

Deployment Configurations

The deployment configurations are stored in the deployment-env.yml file. This file contains metadata related to the service.

• service_id – Service ID. Do not override this!

We dont configure memory or timeout but we use azure default.

• providerMemorySize – We use consumption plan so each instance of the Functions host is limited to 1.5 GB of memory by default.
• providerTimeout – Timeout after which function errors out, we use azure function default 5 minutes.

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. C# template does not have sample test cases 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

TBD by Edward logging solution

Log format: {TIMESTAMP} {LOG_LEVEL} {REQUEST_ID} {LOG_MESSAGE}

Example: 2019-03-05T21:45:29.951 [Information] f7dc181f-f9c4-4341-9f7f-dc0b5e9f41b0 Interesting runtime events (Eg. connection established, data fetched etc.)

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 of the function (functionapp) under each environment. Azure function requires to specify an event source during initial creation.

Azure function has a specific file structure and use function.json to configure function input and output binding. function.json is set during the deployment process based on service catalog so it is not part of function template hence not in the project repo.

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 a storage account, create CDN (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 (CDN) for the service under each environment.