openapi: "3.0.1"
info:
  title: "Performance Dashboard on AWS"
  description: "Backend REST API"
  version: "2021-02-15T15:50:32Z"

security:
  - cognito-authorizer: []

paths:
  # ------------------------------------
  # Public endpoints
  # ------------------------------------
  /public/homepage:
    get:
      operationId: GetPublicHomepage
      security: []
      responses:
        "200":
          description: Contains site information and a list of dashboards
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicHomepage"

  /public/dashboard/friendly-url/{friendlyURL}:
    get:
      operationId: GetPublicDashboardByFriendlyURL
      security: []
      parameters:
        - name: friendlyURL
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A public representation of a dashboard including its widgets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicDashboard"

  /public/dashboard/{id}:
    get:
      operationId: GetPublicDashboardById
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A public representation of a dashboard including its widgets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicDashboard"

  /public/settings:
    get:
      operationId: GetPublicSettings
      security: []
      responses:
        "200":
          description: Public configuration settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicSettings"

  # ------------------------------------
  # Cognito-authenticated endpoints
  # ------------------------------------
  /dashboard:
    get:
      operationId: ListDashboards
      responses:
        "200":
          description: List of dashboards
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Dashboard"

    post:
      operationId: CreateDashboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDashboardRequest"
      responses:
        "200":
          description: Newly created dashboard
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dashboard"

  /dashboard/{id}:
    get:
      operationId: GetDashboardById
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      responses:
        "200":
          description: Dashboard with widgets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dashboard"

    put:
      operationId: UpdateDashboard
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDashboardRequest"
      responses:
        "200":
          description: Dashboard updated successfully

    delete:
      operationId: DeleteDashboard
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      responses:
        "200":
          description: Dashboard deleted successfully

  /dashboard/{id}/archive:
    put:
      operationId: ArchiveDashboard
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveDashboardRequest"
      responses:
        "200":
          description: Dashboard archived successfully
        "409":
          description: Dashboard is not in the expected state

  /dashboard/{id}/publish:
    put:
      operationId: PublishDashboard
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishDashboardRequest"
      responses:
        "200":
          description: Dashboard published successfully
        "409":
          description: Dashboard is not in the expected state

  /dashboard/{id}/draft:
    put:
      operationId: MoveDashboardToDraft
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveDashboardToDraftRequest"
      responses:
        "200":
          description: Dashboard moved to draft successfully
        "409":
          description: Dashboard is not in the expected state

  /dashboard/{id}/publishpending:
    put:
      operationId: MoveDashboardToPublishQueue
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveDashboardToPublishQueueRequest"
      responses:
        "200":
          description: Dashboard moved to publish queue successfully
        "409":
          description: Dashboard is not in the expected state

  /dashboard/{id}/widget:
    post:
      operationId: CreateWidget
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWidgetRequest"
      responses:
        "200":
          description: Widget created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Widget"

  /dashboard/{id}/widget/{widgetId}:
    get:
      operationId: GetWidgetById
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
        - name: widgetId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Widget
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Widget"

    put:
      operationId: UpdateWidget
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
        - name: widgetId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWidgetRequest"
      responses:
        "200":
          description: Widget updated successfully

    delete:
      operationId: DeleteWidget
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
        - name: widgetId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Widget deleted successfully

  /dashboard/{id}/versions:
    get:
      operationId: ListDashboardVersions
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      responses:
        "200":
          description: List of dashboard versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DashboardVersion"

  /dashboard/{id}/widgetorder:
    put:
      operationId: SetWidgetOrder
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetWidgetOrderRequest"
      responses:
        "200":
          description: Widget order saved successfully

  /dashboard/{id}/auditlogs:
    get:
      operationId: ListDashboardAuditLogs
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard Id
          schema:
            type: string
      responses:
        "200":
          description: List of dashboard audit logs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DashboardAuditLog"

  /settings:
    get:
      operationId: GetSettings
      responses:
        "200":
          description: Settings for application
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Settings"

    put:
      operationId: UpdateSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSettingsRequest"
      responses:
        "200":
          description: New settings saved successfully

  /settings/homepage:
    get:
      operationId: GetHomepage
      responses:
        "200":
          description: list of dashboards on homepage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Homepage"

    put:
      operationId: UpdateHomepage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateHomepageRequest"
      responses:
        "200":
          description: New homepage saved successfully

  /dataset:
    get:
      operationId: ListDatasets
      responses:
        "200":
          description: list of datasets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Dataset"

    post:
      operationId: CreateDataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDatasetRequest"
      responses:
        "200":
          description: Widget created successfully

  /dataset/{id}:
    get:
      operationId: GetDatasetById
      parameters:
        - name: id
          in: path
          required: true
          description: Dataset Id
          schema:
            type: string
      responses:
        "200":
          description: dataset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dataset"

  /topicarea:
    get:
      operationId: ListTopicareas
      responses:
        "200":
          description: list of topic areas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TopicArea"

    post:
      operationId: CreateTopicarea
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TopicAreaRequest"
      responses:
        "200":
          description: Topic area created successfully

  /topicarea/{id}:
    get:
      operationId: GetTopicareaById
      parameters:
        - name: id
          in: path
          required: true
          description: Topic area Id
          schema:
            $ref: "#/components/schemas/TopicArea"
      responses:
        "200":
          description: topic area name
          content:
            application/json:
              schema:
                type: string

    put:
      operationId: UpdateTopicarea
      parameters:
        - name: id
          in: path
          required: true
          description: Topic area Id
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TopicAreaRequest"
      responses:
        "200":
          description: Topic area updated successfully

    delete:
      operationId: DeleteTopicarea
      parameters:
        - name: id
          in: path
          required: true
          description: Topic area Id
          schema:
            type: string
      responses:
        "200":
          description: Topic area deleted successfully

  /user:
    get:
      operationId: ListUsers
      responses:
        "200":
          description: list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

    post:
      operationId: CreateUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "200":
          description: User was created

    delete:
      operationId: DeleteUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteUserRequest"
      responses:
        "200":
          description: User(s) were deleted

  /user/role:
    put:
      operationId: UpdateUsersRole
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUsersRoleRequest"
      responses:
        "200":
          description: User(s) updated successfully

  /user/invite:
    post:
      operationId: InviteUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InviteUsersRequest"
      responses:
        "200":
          description: User(s) updated successfully

  # ------------------------------------
  # Dataset Ingestion API endpoints
  # Authenticated via API keys
  # ------------------------------------
  /ingestapi/dataset:
    post:
      operationId: CreateDynamicDataset
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IngestApiDataset"
      responses:
        "200":
          description: dataset was created

  /ingestapi/dataset/{id}:
    put:
      operationId: UpdateDynamicDataset
      parameters:
        - name: id
          in: path
          required: true
          description: Dataset Id
          schema:
            type: string
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IngestApiDataset"
      responses:
        "200":
          description: dataset was created

    delete:
      operationId: DeleteDynamicDataset
      parameters:
        - name: id
          in: path
          required: true
          description: Dataset Id
          schema:
            type: string
      security:
        - api_key: []
      responses:
        "200":
          description: dataset was deleted

components:
  securitySchemes:
    cognito-authorizer:
      type: "apiKey"
      name: "Authorization"
      in: "header"
      x-amazon-apigateway-authtype: "cognito_user_pools"

    api_key:
      type: "apiKey"
      name: "x-api-key"
      in: "header"

  # -----------------------------------------
  # Request/Response schemas
  # ------------------------------------------
  schemas:
    Homepage:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        updatedAt:
          type: string

    UpdateHomepageRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        updatedAt:
          type: string
      required:
        - title
        - description
        - updatedAt

    PublicHomepage:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        dashboards:
          type: array
          items:
            $ref: "#/components/schemas/PublicDashboard"

    PublicDashboard:
      type: object
      description: Public representation of a dashboard
      properties:
        id:
          type: string
        name:
          type: string
        topicAreaId:
          type: string
        topicAreaName:
          type: string
        displayTableOfcontents:
          type: boolean
        description:
          type: string
        updatedAt:
          type: string
        friendlyURL:
          type: string
        widgets:
          type: array
          items:
            $ref: "#/components/schemas/Widget"

    Dashboard:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: number
        parentDashboardId:
          type: string
        topicAreaId:
          type: string
        topicAreaName:
          type: string
        displayTableOfContents:
          type: boolean
        description:
          type: string
        createdBy:
          type: string
        updatedAt:
          type: string
        updatedBy:
          type: string
        submittedBy:
          type: string
        publishedBy:
          type: string
        archivedBy:
          type: string
        deletedBy:
          type: string
        state:
          $ref: "#/components/schemas/DashboardState"
        friendlyURL:
          type: string
        releaseNotes:
          type: string
        widgets:
          type: array
          items:
            $ref: "#/components/schemas/Widget"

    DashboardVersion:
      type: object
      properties:
        id:
          type: string
        state:
          $ref: "#/components/schemas/DashboardState"
        version:
          type: number
        friendlyURL:
          type: string

    DashboardState:
      type: string
      enum:
        - Draft
        - Published
        - Archived
        - PublishPending
        - Inactive

    DashboardAuditLog:
      type: object
      properties:
        itemId:
          type: string
        timestamp:
          type: string
        userId:
          type: string
        event:
          type: string
        modifiedProperties:
          type: array
          items:
            type: object
            properties:
              property:
                type: string
              oldValue:
                type: string
              newValue:
                type: string

    Widget:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        widgetType:
          $ref: "#/components/schemas/WidgetType"
        dashboardId:
          type: string
        order:
          type: number
        updatedAt:
          type: string
        showTitle:
          type: boolean
        content:
          type: object
          oneOf:
            - $ref: "#/components/schemas/TextWidgetContent"
            - $ref: "#/components/schemas/ChartWidgetContent"
            - $ref: "#/components/schemas/MetricsWidgetContent"
            - $ref: "#/components/schemas/ImageWidgetContent"
            - $ref: "#/components/schemas/TableWidgetContent"

    WidgetType:
      type: string
      enum:
        - Text
        - Chart
        - Metrics
        - Table
        - Image

    TextWidgetContent:
      type: object
      properties:
        text:
          type: string

    ChartWidgetContent:
      type: object
      properties:
        title:
          type: string
        chartType:
          type: string
          enum:
            - LineChart
            - ColumnChart
            - BarChart
            - PartWholeChart
        datasetId:
          type: string
        summary:
          type: string
        summaryBelow:
          type: boolean
        datasetType:
          type: string
        s3Key:
          $ref: "#/components/schemas/DatasetS3Key"
        fileName:
          type: string
        columnsMetadata:
          $ref: "#/components/schemas/DatasetColumnMetadata"
        sortByColumn:
          type: string
        sortByDesc:
          type: boolean

    MetricsWidgetContent:
      type: object
      properties:
        title:
          type: string
        datasetId:
          type: string
        oneMetricPerRow:
          type: boolean
        datasetType:
          type: string
        s3Key:
          $ref: "#/components/schemas/DatasetS3Key"

    ImageWidgetContent:
      type: object
      properties:
        title:
          type: string
        imageAltText:
          type: string
        summary:
          type: string
        summaryBelow:
          type: boolean
        s3Key:
          $ref: "#/components/schemas/DatasetS3Key"
        fileName:
          type: string

    TableWidgetContent:
      type: object
      properties:
        title:
          type: string
        datasetId:
          type: string
        summary:
          type: string
        summaryBelow:
          type: boolean
        datasetType:
          type: string
        s3Key:
          $ref: "#/components/schemas/DatasetS3Key"
        fileName:
          type: string
        columnsMetadata:
          $ref: "#/components/schemas/DatasetColumnMetadata"
        sortByColumn:
          type: string
        sortByDesc:
          type: boolean

    DatasetColumnMetadata:
      type: object
      properties:
        columnName:
          type: string
        dataType:
          type: string
          enum:
            - Number
            - Text
        hidden:
          type: boolean

    DatasetS3Key:
      type: object
      properties:
        raw:
          type: string
        json:
          type: string

    PublicSettings:
      type: object
      properties:
        dateTimeFormat:
          type: object
          properties:
            date:
              type: string
            time:
              type: string
        navBarTitle:
          type: string
        topicAreaLabels:
          type: object
          properties:
            singular:
              type: string
            plural:
              type: string
        customLogoS3Key:
          type: string
        customFaviconS3Key:
          type: string
        colors:
          type: object
          properties:
            primary:
              type: string
            secondary:
              type: string
        contactEmailAddress:
          type: string
        contactUsContent:
          type: string

    Settings:
      type: object
      properties:
        publishingGuidance:
          type: string
        dateTimeFormat:
          type: object
          properties:
            date:
              type: string
            time:
              type: string
        updatedAt:
          type: string
        navBarTitle:
          type: string
        topicAreaLabels:
          type: object
          properties:
            singular:
              type: string
            plural:
              type: string
        customLogoS3Key:
          type: string
        customFaviconS3Key:
          type: string
        colors:
          type: object
          properties:
            primary:
              type: string
            secondary:
              type: string
        contactEmailAddress:
          type: string
        adminContactEmailAddress:
          type: string
        contactUsContent:
          type: string

    UpdateSettingsRequest:
      type: object
      properties:
        publishingGuidance:
          type: string
        dateTimeFormat:
          type: object
          properties:
            date:
              type: string
            time:
              type: string
        updatedAt:
          type: string
        navBarTitle:
          type: string
        topicAreaLabels:
          type: object
          properties:
            singular:
              type: string
            plural:
              type: string
        customLogoS3Key:
          type: string
        customFaviconS3Key:
          type: string
        colors:
          type: object
          properties:
            primary:
              type: string
            secondary:
              type: string
        contactEmailAddress:
          type: string
        adminContactEmailAddress:
          type: string
        contactUsContent:
          type: string
      required:
        - updatedAt

    CreateDashboardRequest:
      type: object
      properties:
        topicAreaId:
          type: string
        name:
          type: string
        description:
          type: string
      required:
        - topicAreaId
        - name

    UpdateDashboardRequest:
      type: object
      properties:
        topicAreaId:
          type: string
        name:
          type: string
        description:
          type: string
        updatedAt:
          type: string
        displayTableOfContents:
          type: boolean
      required:
        - topicAreaId
        - name
        - updatedAt

    ArchiveDashboardRequest:
      type: object
      properties:
        updatedAt:
          type: string
      required:
        - updatedAt

    PublishDashboardRequest:
      type: object
      properties:
        updatedAt:
          type: string
        releaseNotes:
          type: string
        friendlyURL:
          type: string
      required:
        - updatedAt

    MoveDashboardToDraftRequest:
      type: object
      properties:
        updatedAt:
          type: string
      required:
        - updatedAt

    MoveDashboardToPublishQueueRequest:
      type: object
      properties:
        updatedAt:
          type: string
        releaseNotes:
          type: string
      required:
        - updatedAt

    CreateWidgetRequest:
      type: object
      properties:
        name:
          type: string
        content:
          type: object
          oneOf:
            - $ref: "#/components/schemas/TextWidgetContent"
            - $ref: "#/components/schemas/ChartWidgetContent"
            - $ref: "#/components/schemas/TableWidgetContent"
            - $ref: "#/components/schemas/ImageWidgetContent"
            - $ref: "#/components/schemas/MetricsWidgetContent"
        widgetType:
          $ref: "#/components/schemas/WidgetType"
        showTitle:
          type: boolean
      required:
        - name
        - content
        - widgetType

    UpdateWidgetRequest:
      type: object
      properties:
        name:
          type: string
        content:
          type: object
          oneOf:
            - $ref: "#/components/schemas/TextWidgetContent"
            - $ref: "#/components/schemas/ChartWidgetContent"
            - $ref: "#/components/schemas/TableWidgetContent"
            - $ref: "#/components/schemas/ImageWidgetContent"
            - $ref: "#/components/schemas/MetricsWidgetContent"
        updatedAt:
          type: string
        showTitle:
          type: boolean
      required:
        - name
        - content
        - updatedAt

    SetWidgetOrderRequest:
      type: object
      properties:
        widgets:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Widget Id
              order:
                type: number
              updatedAt:
                type: string
                description: Last updated time
            required:
              - id
              - order
              - updatedAt
      required:
        - widgets

    CreateUserRequest:
      type: object
      properties:
        emails:
          type: string
        role:
          type: string
      required:
        - emails
        - role

    DeleteUserRequest:
      type: object
      properties:
        usernames:
          type: array
          items:
            type: string
      required:
        - usernames

    UpdateUsersRoleRequest:
      type: object
      properties:
        usernames:
          type: string
        role:
          type: string
      required:
        - usernames
        - role

    InviteUsersRequest:
      type: object
      properties:
        emails:
          type: string
      required:
        - emails

    DatasetMetadata:
      type: object
      properties:
        name:
          type: string
        schema:
          type: string
          enum:
            - Metrics
      required:
        - name

    DatasetDataItems:
      type: object
      properties:
        title:
          type: string
        value:
          type: number
        percentage:
          type: string
          enum:
            - Percentage
            - Currency
        currency:
          type: string
          enum:
            - Dollar $
            - Euro €
            - Pound £
        changeOverTime:
          type: string
        startDate:
          type: string
        endDate:
          type: string
      required:
        - title
        - value

    IngestApiDataset:
      type: object
      properties:
        metadata:
          $ref: "#/components/schemas/DatasetMetadata"
        data:
          type: array
          items:
            $ref: "#/components/schemas/DatasetDataItems"
      required:
        - metadata
        - data

    SourceType:
      type: string
      enum:
        - IngestApi
        - FileUpload

    DatasetSchema:
      type: string
      enum:
        - None
        - Metrics

    Dataset:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        fileName:
          type: string
        s3Key:
          type: object
          properties:
            raw:
              type: string
            json:
              type: string
        updatedAt:
          type: string
        sourceType:
          $ref: "#/components/schemas/SourceType"
        schema:
          $ref: "#/components/schemas/DatasetSchema"

    CreateDatasetRequest:
      type: object
      properties:
        fileName:
          type: string
        s3Key:
          type: object
          properties:
            raw:
              type: string
            json:
              type: string
        schema:
          $ref: "#/components/schemas/DatasetSchema"
      required:
        - fileName
        - s3Key
        - schema

    TopicArea:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdBy:
          type: string
        dashboardCount:
          type: number

    TopicAreaRequest:
      type: object
      properties:
        name:
          type: string
      required:
        - name

    Role:
      type: string
      enum:
        - Admin
        - Editor
        - Publisher

    User:
      type: object
      properties:
        userId:
          type: string
        enabled:
          type: boolean
        userStatus:
          type: string
        sub:
          type: string
        email:
          type: array
          items:
            $ref: "#/components/schemas/Role"
        roles:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string