swagger.yml

swagger: '2.0'
info:
  title: workflow-manager
  description: Orchestrator for AWS Step Functions
  # when changing the version here, make sure to
  # re-run `make generate` to generate clients and server
  version: 0.16.1
  x-npm-package: workflow-manager
schemes:
  - http
produces:
  - application/json

responses:
  BadRequest:
    description: "Bad Request"
    schema:
      $ref: "#/definitions/BadRequest"
  InternalError:
    description: "Internal Error"
    schema:
      $ref: "#/definitions/InternalError"
  NotFound:
    description: "Entity Not Found"
    schema:
      $ref: "#/definitions/NotFound"
  Conflict:
    description: "Conflict with Current State"  #409
    schema:
      $ref: "#/definitions/Conflict"

paths:
  /_health:
    get:
      operationId: healthCheck
      description: Checks if the service is healthy
      responses:
        200:
          description: OK response

  /workflow-definitions:
    get:
      operationId: getWorkflowDefinitions
      description: Get the latest versions of all available WorkflowDefinitions
      responses:
        200:
          description: Successfully fetched all WorkflowDefinitions
          schema:
            type: array
            items:
              $ref: '#/definitions/WorkflowDefinition'
    post:
      operationId: newWorkflowDefinition
      summary: Create a new WorkflowDefinition
      parameters:
        - name: NewWorkflowDefinitionRequest
          in: body
          schema:
            $ref: '#/definitions/NewWorkflowDefinitionRequest'
      responses:
        201:
          description: Successful creation of a new WorkflowDefinition
          schema:
            $ref: '#/definitions/WorkflowDefinition'

  /workflow-definitions/{name}:
    get:
      summary: List WorkflowDefinition Versions by Name
      operationId: getWorkflowDefinitionVersionsByName
      parameters:
        - name: name
          in: path
          type: string
          required: true
        - name: latest
          in: query
          type: boolean
          required: false
          default: true
      responses:
        200:
          description: WorkflowDefinitions
          schema:
            type: array
            items:
              $ref: "#/definitions/WorkflowDefinition"
        404:
          $ref: "#/responses/NotFound"
    put:
      operationId: updateWorkflowDefinition
      summary: Update an exiting WorkflowDefinition
      parameters:
        - name: NewWorkflowDefinitionRequest
          in: body
          schema:
            $ref: '#/definitions/NewWorkflowDefinitionRequest'
        - name: name
          in: path
          type: string
          required: true
      responses:
        201:
          description: Successful creation of a new WorkflowDefinition
          schema:
            $ref: '#/definitions/WorkflowDefinition'
        404:
          $ref: "#/responses/NotFound"

  /workflow-definitions/{name}/{version}:
    get:
      summary: Get a WorkflowDefinition by Name and Version
      operationId: getWorkflowDefinitionByNameAndVersion
      parameters:
        - name: name
          in: path
          type: string
          required: true
        - name: version
          in: path
          type: integer
          required: true
      responses:
        200:
          description: WorkflowDefinition
          schema:
            $ref: "#/definitions/WorkflowDefinition"
        404:
          $ref: "#/responses/NotFound"

  /workflows:
    post:
      summary: Start a Workflow
      operationId: startWorkflow
      parameters:
        - name: StartWorkflowRequest
          description: Parameters for starting a workflow (workflow definition, input, and optionally namespace, queue, and tags)
          in: body
          schema:
            $ref: "#/definitions/StartWorkflowRequest"
      responses:
        200:
          description: Responds with Workflow details including Id, Status, Jobs, Input, Namespace, and WorkflowDefinition
          schema:
            $ref: "#/definitions/Workflow"
        404:
          $ref: "#/responses/NotFound"
        400:
          $ref: "#/responses/BadRequest"

    get:
      summary: Get summary of all active Workflows for a given WorkflowDefinition
      operationId: getWorkflows
      x-paging:
        pageParameter: pageToken
      parameters:
        # TODO: Add date range filters.
        # should be kept in sync with WorkflowQuery model
        - name: limit
          default: 10  # TODO: this can be increased after ark support
          maximum: 10000
          in: query
          type: integer
          description:
            Maximum number of workflows to return.
            Defaults to 10.
            Restricted to a max of 10,000.
        - name: oldestFirst
          in: query
          type: boolean
        - name: pageToken
          in: query
          type: string
        - name: status
          description:
            The status of the workflow (queued, running, etc.).
          in: query
          type: string
        - name: resolvedByUser
          in: query
          type: boolean
          description:
            A flag that indicates whether the workflow has been marked resolved by a user.
        - name: summaryOnly
          description:
            Limits workflow data to the bare minimum - omits the full workflow definition and job
             data.
          in: query
          type: boolean
          default: false
        - name: workflowDefinitionName
          in: query
          type: string
          required: true
      responses:
        200:
          description: Workflow
          schema:
            type: array
            items:
              $ref: "#/definitions/Workflow"
        400:
          $ref: "#/responses/BadRequest"
        404:
          $ref: "#/responses/NotFound"

  /workflows/{workflowID}:
    get:
      summary: Get details for a single Workflow, given a workflowID
      operationId: getWorkflowByID
      parameters:
        - name: workflowID
          in: path
          type: string
          required: true
        - name: fetchHistory
          description: >-
            When true, the execution history will be fetched from SFN along with the workflow summary
          in: query
          type: boolean
          default: false
      responses:
        200:
          description: Workflow
          schema:
            $ref: "#/definitions/Workflow"
        404:
          $ref: "#/responses/NotFound"
    delete:
      summary: Cancel workflow with the given workflowID
      operationId: CancelWorkflow
      parameters:
        - name: workflowID
          in: path
          type: string
          required: true
        - name: reason
          in: body
          schema:
            $ref: "#/definitions/CancelReason"
          required: true
      responses:
        200:
          description: "Workflow cancelled"
        404:
          $ref: "#/responses/NotFound"
    post:
      summary: Resume (restart) a Workflow using job outputs of a completed Workflow from the provided position
      operationId: resumeWorkflowByID
      parameters:
        - name: workflowID
          in: path
          type: string
          required: true
        - name: overrides
          in: body
          required: true
          schema:
            $ref: '#/definitions/WorkflowDefinitionOverrides'
      responses:
        200:
          description: Workflow
          schema:
            $ref: "#/definitions/Workflow"
        404:
          $ref: "#/responses/NotFound"

  /workflows/{workflowID}/resolved:
    post:
      summary: Mark a workflow as resolved by user, given its workflowID. If the workflow is already marked resolved by user, the operation will fail.
      operationId: resolveWorkflowByID
      parameters:
        - name: workflowID
          in: path
          type: string
          required: true
      responses:
        201:
          description: Workflow successfully resolved by user
        404:
          $ref: "#/responses/NotFound"
        409:
          $ref: "#/responses/Conflict"

  /state-resources:
    post:
      summary: Create or Update a StateResource
      operationId: postStateResource
      parameters:
        - name: NewStateResource
          in: body
          schema:
            $ref: '#/definitions/NewStateResource'
      responses:
        201:
          description: StateResource Successfully saved
          schema:
            $ref: "#/definitions/StateResource"

  /state-resources/{namespace}/{name}:
    get:
      summary: Get details about StateResource given the namespace and name
      operationId: getStateResource
      parameters:
        - name: namespace
          in: path
          type: string
          required: true
        - name: name
          in: path
          type: string
          required: true
      responses:
        200:
          description: StateResource
          schema:
            $ref: "#/definitions/StateResource"
        404:
          $ref: "#/responses/NotFound"
    put:
      summary: Create or Update a StateResource for the name and namespace
      operationId: putStateResource
      parameters:
        - name: namespace
          in: path
          type: string
          required: true
        - name: name
          type: string
          in: path
          required: true
        - name: NewStateResource
          in: body
          schema:
            $ref: '#/definitions/NewStateResource'
      responses:
        201:
          description: StateResource Successfully saved
          schema:
            $ref: "#/definitions/StateResource"
        400:
          $ref: "#/responses/BadRequest"
    delete:
      summary: Delete an existing StateResource
      operationId: deleteStateResource
      parameters:
        - name: namespace
          in: path
          type: string
          required: true
        - name: name
          type: string
          in: path
          required: true
      responses:
        200:
          description: StateResource deleted successfully
        404:
          $ref: "#/responses/NotFound"

definitions:
  InternalError:
    type: object
    properties:
      message:
        type: string

  BadRequest:
    type: object
    properties:
      message:
        type: string

  NotFound:
    type: object
    properties:
      message:
        type: string

  Conflict:
    type: object
    properties:
      message:
        type: string

  NewWorkflowDefinitionRequest:
    type: object
    properties:
      version:
        type: integer
      name:
        type: string
      manager:
        $ref: '#/definitions/Manager'
      stateMachine:
        $ref: '#/definitions/SLStateMachine'
      defaultTags:
        description: "defaultTags: object with key-value pairs; keys and values should be strings"
        additionalProperties:
          type: object

  WorkflowDefinition:
    x-db:
      AllowOverwrites: false
      DynamoDB:
        KeySchema:
          - AttributeName: name
            KeyType: HASH
          - AttributeName: version
            KeyType: RANGE
    type: object
    properties:
      id:
        type: string
      version:
        type: integer
      name:
        type: string
      createdAt:
        type: string
        format: date-time
      manager:
        $ref: '#/definitions/Manager'
      stateMachine:
        $ref: '#/definitions/SLStateMachine'
      defaultTags:
        description: "defaultTags: object with key-value pairs; keys and values should be strings"
        additionalProperties:
          type: object

  Manager:
    type: string
    enum:
      - "step-functions"

  Workflow:
    allOf:
      - $ref: '#/definitions/WorkflowSummary'
      - type: object
        properties:
          statusReason:
            type: string
          output:
            # format: json
            type: string
          jobs:
            type: array
            items:
              $ref: '#/definitions/Job'

  WorkflowSummary:
    type: object
    properties:
      id:
        type: string
      createdAt:
        type: string
        format: date-time
      stoppedAt:
        type: string
        format: date-time
      lastUpdated:
        type: string
        format: date-time
      workflowDefinition:
        $ref: '#/definitions/WorkflowDefinition'
      status:
        $ref: '#/definitions/WorkflowStatus'
      namespace:
        type: string
      queue:
        type: string
      input:
        # format: json
        type: string
      resolvedByUser:
        type: boolean
      retryFor:
        description: "workflow-id of original workflow in case this is a retry"
        type: string
      retries:
        description: "workflow-id's of workflows created as retries for this workflow"
        type: array
        items:
          type: string
      tags:
        description: "tags: object with key-value pairs; keys and values should be strings"
        additionalProperties:
          type: object
      lastJob:
        $ref: '#/definitions/Job'

  WorkflowStatus:
    type: string
    enum:
      - "queued"
      - "running"
      - "failed"
      - "succeeded"
      - "cancelled"

  ResolvedByUserWrapper:
    type: object
    properties:
      value:
        type: boolean
      isSet:
        type: boolean

  Job:
    type: object
    properties:
      id:
        type: string
      attempts:
        type: array
        items:
          $ref: '#/definitions/JobAttempt'
      container:
        type: string
      createdAt:
        type: string
        format: date-time
      input:
        # format: json
        type: string
      name:
        type: string
      output:
        # format: json
        type: string
      queue:
        type: string
      startedAt:
        type: string
        format: date-time
      state:
        type: string
      stateResource:
        $ref: '#/definitions/StateResource'
      status:
        $ref: '#/definitions/JobStatus'
      statusReason:
        type: string
      stoppedAt:
        type: string
        format: date-time

  JobStatus:
    type: string
    enum:
      - "created"
      - "queued"
      - "waiting_for_deps"
      - "running"
      - "succeeded"
      - "failed"
      - "aborted_deps_failed"
      - "aborted_by_user"

  JobAttempt:
    type: object
    properties:
      createdAt:
        type: string
        format: date-time
      startedAt:
        type: string
        format: date-time
      stoppedAt:
        type: string
        format: date-time
      containerInstanceARN:
        type: string
      taskARN:
        type: string
      reason:
        type: string
      exitCode:
        type: integer

  StartWorkflowRequest:
    type: object
    properties:
      workflowDefinition:
        # required
        $ref: '#/definitions/WorkflowDefinitionRef'
      input:
        # required
        # format: json
        type: string
      namespace:
        # required
        type: string
      queue:
        # not required (defaults to "default")
        type: string
      tags:
        description: "tags: object with key-value pairs; keys and values should be strings"
        additionalProperties:
          type: object
      idSuffix:
        description: "idSuffix is exclusively used for embedded workflow-manager to append human readable information to the newly created workflow's ID. Workflow IDs are truncated to 80 characters, so some or all of the suffix may be lost"
        type: string

  WorkflowDefinitionRef:
    type: object
    properties:
      name:
        type: string
      version:
        type: integer

  CancelReason:
    type: object
    properties:
      reason:
        type: string

  NewStateResource:
    type: object
    properties:
      name:
        type: string
      namespace:
        type: string
      uri:
        type: string

  StateResource:
    type: object
    properties:
      name:
        type: string
      namespace:
        type: string
      uri:
        type: string
      lastUpdated:
        type: string
        format: date-time
      type:
        $ref: '#/definitions/StateResourceType'

  StateResourceType:
    type: string
    enum:
      - "JobDefinitionARN"
      - "ActivityARN"
      - "LambdaFunctionARN"
      - "TaskARN"

  # States Language Types: https://states-language.net/spec.html
  SLStateMachine:
    type: object
    properties:
      StartAt:
        type: string
      Comment:
        type: string
      Version:
        type: string
        enum: ["1.0"]
      TimeoutSeconds:
        type: integer
      States:
        additionalProperties:
          $ref: '#/definitions/SLState'

  SLState:
    type: object
    properties:
      Type:
        $ref: '#/definitions/SLStateType'
      Resource:
        type: string
      Comment:
        type: string
      Next:
        type: string
      End:
        type: boolean
      Parameters:
        additionalProperties:
          type: object
      InputPath:
        type: string
      ItemsPath:
        type: string
      OutputPath:
        type: string
      ResultPath:
        type: string
      Result:
        type: string
      ResultSelector:
        additionalProperties:
          type: string
      MaxConcurrency:
        type: integer
      Retry:
        x-omitempty: true
        type: array
        items:
          $ref: '#/definitions/SLRetrier'
      Catch:
        x-omitempty: true
        type: array
        items:
          $ref: '#/definitions/SLCatcher'
      TimeoutSeconds:
        type: integer
      HeartbeatSeconds:
        type: integer
      Choices:
        x-omitempty: true
        type: array
        items:
          $ref: '#/definitions/SLChoice'
      Branches:
        x-omitempty: true
        type: array
        items:
          $ref: '#/definitions/SLStateMachine'
      Iterator:
        x-omitempty: true
        $ref: '#/definitions/SLStateMachine'
      Default:
        type: string
      Error:
        type: string
      Cause:
        type: string
      # The below properties apply to `Wait` states
      # http://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-wait-state.html
      Seconds:
        type: integer
      Timestamp:
        type: string
      SecondsPath:
        type: string
      TimestampPath:
        type: string

  SLChoice:
    type: object
    properties:
      Next:
        type: string
      Variable:
        type: string
      # x-nullable: true makes it so that these are pointers
      # in the generated go types. This ensures that
      # 1) you can create choices that involve the zero value of
      #    int and string, and they will appear in the marshalled JSON.
      # 2) these fields are omitted from JSON when not provided
      StringEquals:
        x-nullable: true
        type: string
      StringLessThan:
        x-nullable: true
        type: string
      StringGreaterThan:
        x-nullable: true
        type: string
      StringLessThanEquals:
        x-nullable: true
        type: string
      StringGreaterThanEquals:
        x-nullable: true
        type: string
      NumericEquals:
        x-nullable: true
        type: integer
      NumericLessThan:
        x-nullable: true
        type: number
      NumericGreaterThan:
        x-nullable: true
        type: number
      NumericLessThanEquals:
        x-nullable: true
        type: integer
      NumericGreaterThanEquals:
        x-nullable: true
        type: integer
      BooleanEquals:
        x-nullable: true
        type: boolean
      TimestampEquals:
        x-nullable: true
        type: string
        format: date-time
      TimestampLessThan:
        x-nullable: true
        type: string
        format: date-time
      TimestampGreaterThan:
        x-nullable: true
        type: string
        format: date-time
      TimestampLessThanEquals:
        x-nullable: true
        type: string
        format: date-time
      TimestampGreaterThanEquals:
        x-nullable: true
        type: string
        format: date-time
      And:
        x-omitempty: true
        type: array
        items:
          $ref: '#/definitions/SLChoice'
      Or:
        x-omitempty: true
        type: array
        items:
          $ref: '#/definitions/SLChoice'
      Not:
        $ref: '#/definitions/SLChoice'

  SLRetrier:
    type: object
    properties:
      IntervalSeconds:
        type: integer
      BackoffRate:
        type: number
      ErrorEquals:
        type: array
        items:
          $ref: '#/definitions/SLErrorEquals'
      MaxAttempts:
        type: integer
        minimum: 0
        maximum: 2000

  SLCatcher:
    type: object
    properties:
      ErrorEquals:
        type: array
        items:
          $ref: '#/definitions/SLErrorEquals'
      ResultPath:
        type: string
      Next:
        type: string

  SLStateType:
    type: string
    enum:
      - "Pass"
      - "Task"
      - "Choice"
      - "Wait"
      - "Succeed"
      - "Fail"
      - "Parallel"
      - "Map"

  SLErrorEquals:
    type: string

  WorkflowDefinitionOverrides:
    type: object
    properties:
      StartAt:
        type: string

  # Should be kept in sync with getWorkflows API
  WorkflowQuery:
    type: object
    required:
      - workflowDefinitionName
    properties:
      workflowDefinitionName:
        type: string
      limit:
        type: integer
        default: 10
        maximum: 10000
      oldestFirst:
        type: boolean
      pageToken:
        type: string
      status:
        $ref: '#/definitions/WorkflowStatus'
      summaryOnly:
        type: boolean
        default: false
      resolvedByUserWrapper:
        description: Tracks whether the resolvedByUser query parameter was sent or omitted in the request.
        $ref: '#/definitions/ResolvedByUserWrapper'