openapi: 3.0.0
info:
  title: Planning Status API
  version: '3.0'
  description: >-
    The Planning Status Service keeps track of various planning status results
    for processing trip data and provides endpoints to easily retrieve which
    planning imports succeeded and which failed, when and how.


    *Make sure you request the Auth API first*
  contact:
    name: ''
    email: ''
servers:
  - url: https://planning-status-api.services.simacan.com/api/public/v3
    description: Production Environment
  - url: https://planning-status-api-stg.services.simacan.com/api/public/v3
    description: Staging Environment
paths:
  /get_by_planning_id/{planningUUID}:
    get:
      summary: Get By PlanningId
      description: Get all planning updates for the planning with the provided id (UUID)
      operationId: getByPlanningId
      parameters:
        - name: planningUUID
          in: path
          schema:
            type: string
          description: The unique identifier of the planning itself
          required: true
      responses:
        '200':
          description: >-
            The planning import attempt with all intermediate steps for the
            given ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/planningImportAttempt'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  securitySchemes:
    BearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: >-
        Before any request you do, make sure you have obtained an access token
        from the Auth API. You need to send the access token through an HTTP
        Authorization request header
  schemas:
    planningImportAttempt:
      properties:
        id:
          type: string
          format: uuid
          description: This is the Simacan generated universally unique identifier
          example: 39e8d454-87b4-427d-a4f3-c50ed2677644
        name:
          type: string
          description: The name of the planning
          example: peterson/2020-09-02T12:26:47.585271Z.json
        planningCreationTime:
          type: string
          format: date-time
          description: The creation time of the planning
          example: '2020-09-02T12:26:47.705Z'
        shipper:
          type: string
          description: The shipper to which the planning belongs
          example: peterson
        triggerType:
          type: string
          description: Defines how the job should be triggered
          example: Automatic
        status:
          type: string
          description: Defines current status of the job
          enum:
            - ShouldStart
            - Running
            - Succeeded
            - Failed
          example: ShouldStart
        file:
          type: object
          properties:
            fileName:
              type: string
              description: The name of the file
              example: peterson/2020-09-02T12:26:47.585271Z.json
            directory:
              type: string
              description: The directory where the file resides
              example: simacan-planning-data
        tags:
          type: object
          properties:
            mimeType:
              type: string
              description: Mimetype of the file
              example: application/json
            version:
              type: number
              example: '1'
            schema:
              type: string
              example: json
            source:
              type: string
              example: planning-receive-api
        steps:
          type: array
          items:
            $ref: '#/components/schemas/step'
    step:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Universally unique identifier for this step
          example: 90e66fcb-4be0-4d33-9ee6-60fe999904e5
        endTime:
          type: string
          format: date-time
          description: The time when this planning import step finishes
          example: '2020-09-02T12:26:47.708852Z'
        status:
          type: string
          description: The current status of the planning import
          enum:
            - ShouldStart
            - Running
            - Succeeded
            - Failed
          example: ShouldStart
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errors'
        name:
          type: string
          description: >-
            The name of this step, can be useful to differentiate intermediate
            steps of processing a single planning.

            Such as CSV parsing, SCT sending, etc. This allows you to create an
            audit trail of processing steps
          example: Starting peterson/2020-09-02T12:26:47.585271Z.json
        processingStepType:
          type: string
          example: Starting
    errors:
      type: object
      description: A planning import error
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the error
          example: 15b245b0-6a47-44ae-8bf2-591f430cd368
        message:
          type: string
          description: The message of the error
          example: >-
            (/_id,List(JsonValidationError(List(error.path.missing),WrappedArray())))
  responses:
    '401':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: Authentication credentials were missing or incorrect.
      description: >-
        Unauthorized: Whenever you will get this status, you have either
        provided the wrong credentials or none at all. Check if you bearer token
        has not expired. 
    '403':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: Access to this resource is not allowed.
      description: >-
        Forbidden: You will receive this status, when you successfully supplied
        credentials, but your username does not have the necessary permissions
        for the resource.
    '404':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: The requested resource was not found.
      description: >-
        Not Found: Whenever you will get a 404, you are probably using a
        malformed or incorrect URL.
tags: []
security:
  - BearerAuth: []
