REST API

Corteza uses standard Go’s HTTP servers and handlers with chi to handle request routing.

Request handling

Request flow diagram:
Figure 1. Request flow diagram:
General outline of an HTTP request:

  1. request handlers convert the request into a proper structure,

  2. the service initializes the action parameters (used for the action log),

  3. requested resources are loaded and access permissions are checked,

  4. the appropriate operation is performed,

  5. the request handler prepares the response, most commonly in the JSON format.

API endpoints

Endpoints are defined with */rest.yaml files (/(compose|system|federation|automation)/rest.yaml). The code generation tool uses these rest.yaml files to generate the boilerplate request and response handling logic.

The rest.yaml files are used to generate the boilerplate code to handle request and response formatting (rest/request/.go and rest/handlers/.go). You can run the code generation tool with make codegen CLI command.

Handlers read and normalize request data into request structures and pass them on to controllers. Controllers are functions that handle a request and route it forward to internal service, and format the final output.

Controllers were initially developed to solve CRUD operations. Further development of Corteza platform outgrew that, so you may notice some peculiar patterns (returning http.HandlerFunc functions from handlers, for instance)

API documentation

API documentation is provided by Swagger using the open API. The open API format is generated using the openapi3-converter tool.

The converter tool generates a series of {resource}.yaml files in the /swagger directory. If corteza-server is in the same directory as the converter tool, the files are moved to the corteza-server/docs directory and the /swagger directory.

To generate the static HTML API documentation served by the corteza-server, run the make docs command within the corteza-server repository. The static HTML files are generated in the corteza-server/docs/ directory.

Extending the tool

The entirety of the converting process is done in the openapi3-converter/tools/convert.js.

Adding new definitions

Adding a new definition adds a new entry to the const namespaces = […​] array. Rebuild the open API definitions using the yarn convert:yaml command.

An example of a new resource foo:
const namespaces = [
  {
    path: `${path}/system/rest.yaml`,
    namespace: 'system',
    className: 'System',
  },
  {
    path: `${path}/compose/rest.yaml`,
    namespace: 'compose',
    className: 'Compose',
  },
  {
    path: `${path}/federation/rest.yaml`,
    namespace: 'federation',
    className: 'Federation',
  },
  {
    path: `${path}/foo/rest.yaml`,
    namespace: 'foo',
    className: 'Foo',
  },
]

Adding new endpoints

The tool uses rest.yaml files defined in the corteza-server repository. Add a new endpoint in the corresponding rest.yaml file and run the yarn convert:yaml command to rebuild the definitions.

Plans for the future

  • Removing the home-brew API definitions and replacing them with OpenAPI 3.

  • Better support for update and partial update requests (PUT/PATCH).