REST API

API Reference

This section provides detailed information about the available endpoints in the Governor REST API.

openapi: 3.0.1
info:
  title: "Governor External API"
  description: |
    This API provides external access to the Governor services
  version: "1.0.0"

x-package: io.synthesized.governor.external.api

paths:
  /external/api/v1/healthy:
    get:
      operationId: getExternalHealth
      description: Health check
      tags:
        - external_health
      responses:
        "200":
          description: Healthcheck API
          content:
            application/json:
              schema:
                type: string
                nullable: false

  /external/api/v1/workflow/{workflow_id}/run:
    description: Run specified workflow
    post:
      operationId: runWorkflow
      tags:
        - external_workflow_run
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
            nullable: false
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiWorkflowRunResponse"

  /external/api/v1/workflow-run/{id}:
    description: Get workflow run
    get:
      operationId: getWorkflowRun
      tags:
        - external_workflow_run
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
            nullable: false
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiWorkflowRunResponse"

  /external/api/v1/workflow/{workflow_id}/runs:
    description: Get workflow runs
    get:
      operationId: listWorkflowRuns
      tags:
        - external_workflow_run
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
            nullable: false
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                nullable: false
                items:
                  $ref: "#/components/schemas/ApiWorkflowRunResponse"

components:
  schemas:
    ApiWorkflowRunResponse:
      type: object
      title: RunWorkflowResponse
      nullable: false
      properties:
        workflow_run_id:
          nullable: false
          type: integer
          format: int64
        workflow_run_status:
          $ref: '#/components/schemas/ApiWorkflowRunStatus'
        start_date:
          type: string
          format: date-time
          example: "2021-01-30T08:30:00Z"
        end_date:
          type: string
          format: date-time
          example: "2021-01-30T08:30:00Z"
        user_id:
          type: integer
          format: int64
        error_message:
          type: string

    ApiWorkflowRunStatus:
      enum:
        - QUEUED
        - RUNNING
        - COMPLETED
        - FAILED
        - STOPPING
        - STOPPED

Authorization

To use the Governor REST API, you must include a valid access key in the request headers. This key authenticates the request and identifies the user making the request.

You can generate an access key from the Governor web interface. For instructions on how to do this, see Generating an Access Key.

Include the access key in the X-Access-Key header of your request.

Examples

Check API availability

The health check endpoint allows you to verify the accessibility of the API. To use this endpoint, replace {your_access_key} with the actual access key you generated in the previous step.

If you’re deploying with Docker Compose, you should replace "https://your-domain.com" with localhost:8081. This ensures that you’re making requests to the correct location where your application is running when using Docker Compose.

curl -X GET \
  https://your-domain.com/external/api/v1/healthy \
  -H 'X-Access-Key: {your_access_key}'

The expected response is: OK

Run workflow

To run a workflow, replace {workflow_id} with the ID of the workflow you want to run and {your_access_key} with your actual access key.

curl -X POST \
  https://your-domain.com/external/api/v1/workflow/{workflow_id}/run \
  -H 'X-Access-Key: {your_access_key}'

The response will look something like this:

{
  "workflow_run_id": 1,
  "workflow_run_status": "RUNNING",
  "start_date": "2024-04-25T22:24:52.84434075Z",
  "end_date": null,
  "user_id": 1,
  "error_message": null
}

Get workflow run status

To get the status of a workflow run, replace {workflow_run_id} with the ID of the workflow run from the previous step and {your_access_key} with your actual access key.

curl -X GET \
  https://your-domain.com/external/api/v1/workflow-run/{workflow_run_id} \
  -H 'X-Access-Key: {your_access_key}'

The response will look something like this:

{
  "workflow_run_id": 1,
  "workflow_run_status": "COMPLETED",
  "start_date": "2024-04-25T22:24:52.844341Z",
  "end_date": "2024-04-25T22:25:04.863765Z",
  "user_id": 1,
  "error_message": null
}

Get all workflow runs by workflow ID

To get all workflow runs for workflow, replace {workflow_id} with the ID of the workflow run from the previous step and {your_access_key} with your actual access key.

curl -X GET \
  https://your-domain.com/external/api/v1/workflow/{workflow_id}/runs \
  -H 'X-Access-Key: {your_access_key}'

The response will look something like this:

[
    {
      "workflow_run_id": 1,
      "workflow_run_status": "COMPLETED",
      "start_date": "2024-04-25T22:24:52.844341Z",
      "end_date": "2024-04-25T22:25:04.863765Z",
      "user_id": 1,
      "error_message": null
    }
]