openapi: 3.0.1

info:
  title: gPROMS Web Applications Platform API
  description: "The gPROMS Web Applications Platform (gWAP) API provides a machine-to-machine interface for interacting with the platform."
  version: 1.0.0

servers:
- url: /api/v1

paths:
  /apps:
    get:
      tags:
      - Applications
      summary: List all applications
      responses:
        200:
          description: OK
          content:
            application/json:
              example:
                data:
                  - id: 843fc69a-4688-440d-a48a-9097d84fa447
                    metadata:
                      name: Batch reactor dynamic simulation demo
                      type: Dynamic-Simulation
                      executor: defaultExecutor::latest
                      created: 1721226631601
                      author: SPSE - gWAP Team
                      description: PML Batch Reactor Example
                      exportedFrom: unknown
                meta:
                  productVersion: 3.1.0
                  apiVersion: 1.0.0
        401:
          $ref: '#/components/responses/UnauthorizedError'

    post:
      tags:
      - Applications
      summary: Upload an application
      requestBody:
        content:
          multipart/form-data:
              schema:
                type: object
                properties:
                  appZipFile:
                    type: string
                    format: binary
      responses:
        201:
          description: Created
          content:
            application/json:
              example:
                data:
                  id: 843fc69a-4688-440d-a48a-9097d84fa447
                  metadata:
                    name: Batch reactor dynamic simulation demo
                    type: Dynamic-Simulation
                    executor: defaultExecutor::latest
                    created: 1721226631601
                    author: SPSE - gWAP Team
                    description: PML Batch Reactor Example
                    exportedFrom: unknown
                meta:
                  productVersion: 3.1.0
                  apiVersion: 1.0.0
        400:
          description: Bad Request
          content:
            application/json:
              example:
                errors:
                  - title: Bad Request
                    detail: appZipFile is not a valid zip file
        401:
          $ref: '#/components/responses/UnauthorizedError'
        500:
          description: Internal Server Error
          content:
            application/json:
              example:
                errors:
                  - title: Internal Server Error
                    detail: An unexpected error occurred

  /apps/{appId}/zip:
    get:
      tags:
        - Applications
      summary: Download an application
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          example: d2a74a55-0ffc-4691-ad11-73c42e83ad7c
      responses:
        200:
          description: OK
          content:
            application/zip:
              schema:
                type: string
                format: binary
                example: Binary representation of the app zip file
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a is not allowed to download app d2a74a55-0ffc-4691-ad11-73c42e83ad7c
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: Application does not exist.

  /apps/{appId}:
    put:
      tags:
      - Applications
      summary: Update an application
      requestBody:
        content:
          multipart/form-data:
              schema:
                type: object
                properties:
                  appZipFile:
                    type: string
                    format: binary
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          example: d2a74a55-0ffc-4691-ad11-73c42e83ad7c
      responses:
        200:
          description: OK
          content:
            application/json:
              example:
                data:
                  id: 843fc69a-4688-440d-a48a-9097d84fa447
                  metadata:
                    name: Batch reactor dynamic simulation demo
                    type: Dynamic-Simulation
                    executor: defaultExecutor::latest
                    created: 1721226631601
                    author: SPSE - gWAP Team
                    description: PML Batch Reactor Example
                    exportedFrom: unknown
                meta:
                  productVersion: 3.1.0
                  apiVersion: 1.0.0
        400:
          description: Bad Request
          content:
            application/json:
              example:
                errors:
                  - title: Bad Request
                    detail: appZipFile is not a valid zip file
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a is not allowed to manage application. This is restricted to the application owner and the gWAP_Admin
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: Application does not exist.

    delete:
      tags:
      - Applications
      summary: Delete an application
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          example: d2a74a55-0ffc-4691-ad11-73c42e83ad7c
      responses:
        204:
          description: No Content
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a is not allowed to delete app d2a74a55-0ffc-4691-ad11-73c42e83ad7c
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: Application does not exist.
  
  /sources/apps/{appId} :
    get:
      tags:
        - Sources
      summary: List external data sources for a specific app
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              example:
                data:
                  - id: 843fc69a-4688-440d-a48a-9097d84fa447
                    name: Experiment_1_475K_IC1
                    description: First experiment at 475K
                    type: EXCEL
                meta:
                  productVersion: 3.1.0
                  apiVersion: 1.0.0
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: Application does not exist.

  /sources/{sourceId} :
    get:
      tags:
        - Sources
      summary: Get single external data source
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 843fc69a-4688-440d-a48a-9097d84fa447
                    name: Experiment_1_475K_IC1
                    description: First experiment at 475K
                    type: EXCEL
                  meta:
                    productVersion: 3.1.0
                    apiVersion: 1.0.0
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: External data source does not exist.

    patch:
      tags:
        - Sources
      summary: Edit external data source
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            example:
              data:
                name: Experiment_1_475K_IC1
                description: First experiment at 475K
      responses:
        200:
          description: OK
          content:
            application/json:
              example:
                data:
                  id: 843fc69a-4688-440d-a48a-9097d84fa447
                  name: Experiment_1_475K_IC1
                  description: First experiment at 475K
                  type: EXCEL
        400:
          description: Bad Request
          content:
            application/json:
              example:
                errors:
                  - title: Bad Request
                    detail: Name cannot be empty
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: External data source does not exist.

    delete:
      tags:
        - Sources
      summary: Delete external data source
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: No Content
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: External data source does not exist.

  /sources/excel/{sourceId}:
    get:
      tags:
        - Excel sources
      summary: Download Excel source file
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: External data source does not exist.

  /sources/excel/template:
    post:
      tags:
        - Excel sources
      summary: Download empty Excel template
      parameters:
        - name: fileName
          in: query
          required: false
          schema:
            type: string
      requestBody:
        description: One or more distinct groups of variables can be passed. Each with at least a single variable. A time axis can optionally be specified at either the group or variable level. Placeholder values can be optionally provided for both variables and time.
        content:
          application/json:
            example:
              data:
                - color: '#FFFFFF'
                  time:
                    uom: s
                    placeholder:
                      - 60
                      - 90
                      - 120
                  variables:
                    - name: Measurement
                      path: Flowsheet.measurement
                      uom: '-'
                      placeholder:
                        - 0
                        - 1
                        - 2
      responses:
        200:
          description: OK
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        400:
          description: Bad Request

  /sources/apps/{appId}/excel :
    post:
      tags:
        - Excel sources
      summary: Create external data source from an Excel file
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
              schema:
                type: object
                properties:
                  file:
                    type: string
                    format: binary
      responses:
        201:
          description: Created
          content:
            application/json:
              example:
                data:
                  - id: 843fc69a-4688-440d-a48a-9097d84fa447
                    name: Experiment_1_475K_IC1
                    description: First experiment at 475K
                    type: EXCEL
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: Application does not exist.

  /sources/apps/{appId}/json:
    post:
      tags:
        - JSON sources
      summary: Create external data source from JSON-formatted data
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: query
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            example:
              data:
                - time: 0
                  variables:
                    - name: Flowsheet.scalar
                      value: 1.0
                    - name: Flowsheet.scalar.string
                      value: wombat
      responses:
        201:
          description: Created
          content:
            application/json:
              example:
                data:
                  id: a40448bf-a478-4c25-aa09-450174a08094
                  name: 'Source'
                  description: ""
                  type: JSON
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: Forbidden
          content:
            application/json:
              example:
                errors:
                  - title: Forbidden
                    detail: User 78da4e1c-48d0-47e0-bece-f7619995ca7a does not have ACCESS permission for app 843fc69a-4688-440d-a48a-9097d84fa447
        404:
          description: Not Found
          content:
            application/json:
              example:
                errors:
                  - title: Not Found
                    detail: Application does not exist.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          example:
            errors:
                - title: Unauthorized
                  detail: Access token is missing or invalid
security:
  - bearerAuth: []