Long running operations REST API (draft)

example.yaml

swagger: "2.0"
info:
  title: ASYNC REST API
  version: 0.0.1
  contact:
    name: ASYNC TEAM
    url: https://example.com/
host: "example.com"
basePath: /api/v1
schemes:
  - https
consumes:
  - "application/json"
produces:
  - "application/json"
paths:
  "/async/{resource_id}":
    get:
      summary: "Poll an async operation (Sync)"
      operationId:
      parameters:
        - name: resource_id
          in: path
          required: true
      responses:
        '200':
          description: "in progress"
          schema:
            $ref: '#/definitions/AsyncOperationInProgress'
        '303':
          description: "completed"
          schema:
            $ref: '#/definitions/AsyncOperationCompleted'
        '410':
          description: "cancelled"
          schema:
            $ref: '#/definitions/AsyncOperationCancelled'
        '404':
          description: "operation not exists"
    delete:
      summary: "Cancel an async operation (Async)"
      operationId:
      parameters:
        - name: resource_id
          in: path
          required: true
      responses:
        '202':
          description: "cancel will happen"
        '405':
          description: "cancel is not possible"
        '404':
          description: "operation not exists"

  "/resources":
    get:
      summary: "Show all resources (Sync)"
      operationId:
      parameters:
        - name: service_name
          in: body
          schema:
            $ref: '#/definitions/ServiceName'
          required: false
        - name: environment
          in: body
          schema:
            $ref: '#/definitions/EnvironmentName'
          required: false
      responses:
        '200':
          description: "resource list"
        '404':
          description: "resources are not exist"

  "/resources/{domain_name}":
    get:
      summary: "Get resource details (Sync)"
      operationId:
      parameters:
        - name: domain_name
          in: path
          required: true
        - name: service_name
          in: body
          schema:
            $ref: '#/definitions/ServiceName'
          required: true
      responses:
        '200':
          description: "resource details"
        '404':
          description: "resource not exists"
    put:
      summary: "Update an existing resource (Async)"
      operationId:
      parameters:
        - name: domain_name
          in: path
          required: true
        - name: service_name
          in: body
          schema:
            $ref: '#/definitions/ServiceName'
          required: true
        - name: environment
          in: body
          schema:
            $ref: '#/definitions/EnvironmentName'
          required: true
      responses:
        '202':
          description: "request accepted"
        '404':
          description: "resource not exists"
        '409':
          description: "another async op is in progress"
    post:
      summary: "Create new resource (Async)"
      operationId:
      parameters:
        - name: domain_name
          in: path
          required: true
        - name: service_name
          in: body
          schema:
            $ref: '#/definitions/ServiceName'
          required: true
        - name: environment
          in: body
          schema:
            $ref: '#/definitions/EnvironmentName'
          required: true
      responses:
        '202':
          description: "request accepted"
        '404':
          description: "resource not exists"
        '409':
          description: "another async op is in progress"
    delete:
      summary: "Delete an existing resource (Async)"
      operationId:
      parameters:
        - name: domain_name
          in: path
          required: true
        - name: service_name
          in: body
          schema:
            $ref: '#/definitions/ServiceName'
          required: true
      responses:
        '202':
          description: "request accepted"
        '404':
          description: "resource not exists"
        '409':
          description: "another async op is in progress"

definitions:
  AsyncOperationInProgress:
    type: object
    properties:
      identifier:
        type: uri
      start:
        type: string
        format: date-time
      cancel:
        type: uri
      messages:
        requied: false
        type: array
        items:
          type: string
    required:
      - identifier
      - start

  AsyncOperationCompleted:
    type: object
    properties:
      identifier:
        type: uri
      start:
        type: string
        format: date-time
      stop:
        type: string
        format: date-time
      failure_message:
        description: "single line problem statement"
        type: string
      failure_details:
        description: "stack trace"
        type: array
        items:
          type: string
    required:
      - identifier
      - start
      - stop

  AsyncOperationCancelled:
    type: object
    properties:
      identifier:
        type: uri
      start:
        type: string
        format: date-time
      stop:
        type: string
        format: date-time
    required:
      - identifier
      - start
      - stop

  ServiceName:
    type: string

  EnvironmentName:
    type: string