Codon: REST Workflow Framework

In any Web API application each endpoint defines a set of tasks interconnected, concurrently or serially, by data flows until the relevant data is aggregated and returned to the requesting client. These series of tasks form a workflow.

The specification of a Web API application includes three components:

• Swagger specification for the service
• Swagger specification for the upstream clients
• Workflow specification for tasks to be performed when an endpoint of the service is hit

Codon generates a Go REST service just by writing YML!

After reading through this page you can read the tutorial for something more specific.

Installation

Set up your Golang development environment (Getting Started). Set your GOPATH and GOBIN directories. Also add GOBIN to your PATH so that golang tools can be used in command line.

Download the latest binary from Github releases and put it in your GOBIN directory. Or to install from source do:

mkdir -p $GOPATH/src/github.com/flowgen
cd $GOPATH/src/github.com/flowgen
git clone [email protected]:flowgen/go-codon.git
cd go-codon
make install

Bootstrapping

Navigate or create an empty folder for your new project in the GOPATH. Once in the folder run:

codon init

This will bootstrap your project and setup files and folders needed for subsequent generation of the code. Details for each folder and what it does is present in their respective folders.

Setting up Upstream Services

Place swagger specification for all your upstream APIs in the folder spec/clients. These will be converted to client libraries. The name of the client library will be decided by the name of the swagger YML file. If you place newapi.yml the client library name will be newapi.

Generated libraries will have to be initialized for specific upstream endpoints. Clients of these libraries will have to be declared in the config file config.yml at the project's root folder like:

endpoints:
  newapi1:
    scheme: https
    host: newapi1.example.com
    client: newapi

Adding this section to your config file will instantiate an instance of newapi library with these settings and object name as Newapi1.

In the config file you can also add any constants like boolean flags or authentication keys in the section contants. These contants will be available for use in the workflow.

Designing your APIs

Write a swagger specification for the API you will be serving using this application, and place it in spec/server/main.yml. The file name must be main.yml. You can use JSON references supported by swagger to split it into multiple files but the starting point of the spec should be main.yml.

Codon adds two extensions to Swagger specification: x-workflow and x-template.

Workflow extension is used to specify the workflow name to trigger for an Operation Object. For example:

paths:
  /health:
    get:
      x-workflow: get_health
      responses:
        200:
          description: ELB Health check
          schema:
            $ref: '#/definitions/HealthResponse'

Hitting /health with GET request will trigger the get_health workflow.

Template extension can specify template details for post-processing. More details can be found here.

Writing the workflow

Workflow DSL specification can be found here. Workflows should be placed in the folder spec/server/workflows. You can use any directory structure within this folder but workflow names must be unique as they are used to reference them.

Generating code

Run the following make command to generate code:

make generate

This should generate all the required go code for this service based on your spec.

Partial Generation of code

Generating only portions of the project during development might be useful. Run the following make command to generate just the workflow:

make ARGS="-w" generate

-w is passed on to underlying codon command. Specifying -s and -c will build server and upstream client components as well.

Building the server

After generating the code from specification, run

make build

This will build the code and place a binary in your project folder. You might have to fix the build command in the Makefile.

Adding middlewares

go-swagger abstracts out the router for the server in its go-openapi runtime project. But it provides net/http interfaces to configure your server with middlewares and any other one time initialization you need to do. This is present in server/restapi/configure_<service_name>.go after generating the code. Explanation for each configure function is provided in comments. This file is generated only once and is to be committed in your repository.

Editing code generator templates

Code generation is handled through templates. These templates are present in spec/templates. They can be edited to change generated code.

Cleaning up and committing changes

Generated code need not be committed in your repository. To clean up run (not implemented yet):

make clean

This will remove all the generated code and leave behind just the specifications, custom actions, and the server configuration code (for middlewares etc.)