openapi: 3.0.1
info:
  title: Cytoscape Service-App REST API
  description: |+
    This [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) document defines the Cytoscape Service-App 
    REST Service API which is used by Cytoscape on the Web for Service-Apps.

    This document and all references to the Cytoscape Service-App REST API, source code and ancillary documentation are copyrighted: *© 2013-2024, 
    The Regents of the University of California, The Cytoscape Consortium.  All rights reserved.*  Please abide with the 
    [Terms of Use, Licensing and Sources](https://home.ndexbio.org/disclaimer-license/). Likewise, the [Swagger-UI](https://github.com/swagger-api/swagger-ui) 
    document reader that displays this OpenAPI document is copyrighted by *Smartbear Software*. Its open-source software license is found 
    [here](https://github.com/swagger-api/swagger-ui/blob/master/LICENSE).

  version: 1.0.0
servers:
- url: /example
  description: Cytoscape Service-App REST API
- url: "{Host}"
  description: |
    The host server URL can be overridden.
  variables:
    Host:
      default: /example
paths:
  /{id}:
    get:
      summary: Gets result of task
      description: |-
        NOTE: For incomplete/failed jobs only Status, message, progress, and walltime will
        be returned in JSON
      operationId: getResult
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyResult'
        "400":
          description: Task not found
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'
    delete:
      summary: "Deletes task associated with {id} passed in"
      operationId: deleteRequest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Delete request successfully received
        "400":
          description: Not found
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'
  
  /:
    get:
      summary: Gets meta data about this service/algorithm
      description: Provides detailed information about algorithm offered by this Service-App
      operationId: getMetaData
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyMetaData'
        "400":
          description: Task not found
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'
    post:
      summary: Submits task
      description: "Payload in JSON format needs to have data along with name of algorithm\
        \ to run and any algorithm specific parameters. Information about what algorithms\
        \ are availableand what are the custom parameters can obtained by visiting\
        \ the 'algorithms'endpoint \n\nThe service should upon post return 202 and\
        \ set location to resource to poll for result. Which will\nMatch the URL of\
        \ GET request below."
      operationId: request
      requestBody:
        description: Request as json
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CyRequest'
        required: true
      responses:
        "202":
          description: |
            The task was successfully submitted to the Service-App. Visit the URL specified in Location field in HEADERS to get status and resultsIn addition, the id(s) of the task(s) are returned as json
          headers:
            Location:
              description: URL containing resource generated by this request
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyRequestId'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'
  /{id}/status:
    get:
      summary: Gets status of task
      description: This lets caller get status without getting the full result back
      operationId: getRequestStatus
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyResultStatus'
        "400":
          description: Task not found
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'
  /status:
    get:
      summary: Gets server status
      description: "Gets version, load, and diskusage of server"
      operationId: status
      responses:
        "200":
          description: Server Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyServerStatus'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CyErrorResponse'

components:
  schemas:
    CyErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Error code to help identify issue
        message:
          type: string
          description: Human readable description of error
        description:
          type: string
          description: More detailed description of error
        stackTrace:
          type: string
          description: Stack trace of error
        threadId:
          type: string
          description: Id of thread running process
        timeStamp:
          type: string
          description: UTC Time stamp in YYYY-MM-DD_HH:MM.S
    CyMetaData:
      type: object
      properties:
        name:
          type: string
          description: Service-App Name
        parameters:
          uniqueItems: true
          type: array
          description: Any custom parameters this Service-App accepts
          items:
            $ref: '#/components/schemas/CyMetaDataParameter'
        version:
          type: string
          description: Version
        cyWebActions:
          type: array
          description: List of action to be performed with result by caller. Elements
            of list can be one of the allowable values
          items:
            type: string
            description: List of action to be performed with result by caller. Elements
              of list can be one of the allowable values
            enum:
            - addNetworks
            - addTables
            - updateLayouts
            - updateNetwork
            - updateSelection
            - updateTables
          enum:
          - addNetworks
          - addTables
          - updateLayouts
          - updateNetwork
          - updateSelection
          - updateTables
        description:
          type: string
          description: Description of this Service-App
        author:
          type: string
          description: Author(s) of this Service-App
        email:
          type: string
          description: Email contact for this Service-App
        website:
          type: string
          description: Website for this Service-App
        codeRepository:
          type: string
          description: URL of code repository for this Service-App
        tutorial:
          type: string
          description: URL of tutorial for this Service-App
        citation:
          type: string
          description: Citation for this Service-App
        cyWebMenuItem:
          $ref: '#/components/schemas/CyWebMenuItem'
        serviceInputDefinition:
          $ref: '#/components/schemas/CyServiceInputDefinition'
    CyMetaDataParameter:
      type: object
      properties:
        displayName:
          type: string
          description: Display name for parameter
        description:
          type: string
          description: Parameter description
        type:
          type: string
          description: Type of parameter
          enum:
          - text
          - dropDown
          - radio
          - checkBox
          - nodeColumn
          - edgeColumn
          - flag
        valueList:
          type: array
          description: Values to put into 'dropDown' type field
          items:
            type: string
            description: Values to put into 'dropDown' type field
        defaultValue:
          type: string
          description: Default value for parameter
        validationType:
          type: string
          description: Type of validation to perform
          enum:
          - number
          - digits
          - string
        validationHelp:
          type: string
          description: Text to display if validation fails
        validationRegex:
          type: string
          description: Regular expression that is applied to parameters of 'type' string
        columnTypeFilter:
          type: string
          description: "Only used for nodes/edges column type. If defined, Cytoscape\
            \ Web uses it to filter what node/edge columns to display. If omitted,\
            \ all columns will be listed"
          enum:
          - list
          - number
          - wholenumber
          - list_of_number
          - list_of_wholenumber
          - string
          - long
          - integer
          - double
          - boolean
          - list_of_string
          - list_of_long
          - list_of_integer
          - list_of_double
          - list_of_boolean
        minValue:
          type: number
          description: "If set and parameter is of type 'number' or 'digits',  values\
            \ below this should NOT be allowed"
        maxValue:
          type: number
          description: "If set and parameter is of type 'number' or 'digits',  values\
            \ above this should NOT be allowed"
      description: Parameter that can be passed to Service-App
    CyWebMenuItem:
      type: object
      properties:
        root:
          type: string
          description: Top level menu to place this service
          example: Apps
        path:
          type: array
          description: Service menu path and name
          items:
            $ref: '#/components/schemas/CyWebMenuItemPath'
      description: Defines menu for service
    CyWebMenuItemPath:
      type: object
      properties:
        name:
          type: string
          description: Menu name
          example: My App
        gravity:
          type: integer
          description: "Sets menu gravity, higher values mean lower on menu"
          format: int32
          example: 10
      description: Menu or submenu item
    CyInputColumn:
      type: object
      properties:
        name:
          type: string
          description: The label text of the dropdown list. It will also be used as
            the column name in the generated data block.
        description:
          type: string
          description: A short description of the column. Used as a hint in the UI.
        columnName:
          type: string
          description: Name of the column that should be automatically included. No
            UI control will be generated for this column. Treated like a preselected
            value for name attribute.
        dataType:
          type: string
          description: "Data type of the attribute. When defined, Cytoscape Web uses\
            \ it to filter the dropdown list. If omitted, the dropdown will contain\
            \ all columns."
          enum:
          - list
          - number
          - wholenumber
          - list_of_number
          - list_of_wholenumber
          - string
          - long
          - integer
          - double
          - boolean
          - list_of_string
          - list_of_long
          - list_of_integer
          - list_of_double
          - list_of_boolean
        allowMultipleSelection:
          type: boolean
          description: "When set to true, all selected columns in the dropdown will\
            \ be used to serialize the data, otherwise only one column can be selected"
        defaultColumnName:
          type: string
          description: "(Optional) The default selection in the column name dropdown.\
            \ If the column specified in field doesn't exist in node or edge table,\
            \ no selection will be make."
      description: List of columns that need to be created. For type of 'nodes' and
        'edges' only.
    CyInputNetwork:
      type: object
      properties:
        format:
          type: string
          description: Denotes format of returned data. 'cx2' returns CX2 format.
          example: cx2
          enum:
          - cx2
          - edgelist
        model:
          type: string
          description: Denotes network content returned. 'network' denotes full network
            data and 'graph' denotes bare network (ids only)
          example: network
          enum:
          - network
          - graph
      description: Defines structure of data requested by Service-App. For type of 'network'
        only.
    CyServiceInputDefinition:
      type: object
      properties:
        type:
          type: string
        scope:
          type: string
        inputNetwork:
          $ref: '#/components/schemas/CyInputNetwork'
        inputColumns:
          type: array
          description: List of columns that need to be created. For type of 'nodes'
            and 'edges' only.
          items:
            $ref: '#/components/schemas/CyInputColumn'
      description: Defines data this Service-App expects to receive
    CyResultStatus:
      type: object
      properties:
        id:
          type: string
          description: Id of Cytoscape Service-App Request
          example: 261fb9b7-75af-4f1a-9caa-e57a4b5fc349
        status:
          type: string
          description: "Status of task can be (submitted,processing,complete,failed)"
          enum:
            - submitted
            - processing
            - complete
            - failed
          example: submitted
        message:
          type: string
          description: null or a message denoting a possible issue
        progress:
          type: integer
          description: int between 0 and 100 denoting progress of task
          format: int32
        wallTime:
          type: integer
          description: Walltime in milliseconds task took to run
          format: int64
        startTime:
          type: integer
          description: Time in milliseconds since 1969 epoch when task started
          format: int64
    CyResult:
      type: object
      properties:
        id:
          type: string
          description: Id of Cytoscape Service-App REST Request
          example: 261fb9b7-75af-4f1a-9caa-e57a4b5fc349
        status:
          type: string
          description: "Status of task can be (submitted,processing,complete,failed)"
          example: submitted
        message:
          type: string
          description: null or a message denoting a possible issue
        progress:
          type: integer
          description: int between 0 and 100 denoting progress of task
          format: int32
        wallTime:
          type: integer
          description: Walltime in milliseconds task took to run
          format: int64
        startTime:
          type: integer
          description: Time in milliseconds since 1969 epoch when task started
          format: int64
        result:
          $ref: '#/components/schemas/JsonNode'
    JsonNode:
      type: object
      description: data as json fragment
    CyRequestId:
      type: object
      properties:
        id:
          type: string
          description: Id of Cytoscape Service-App REST Request
          example: 261fb9b7-75af-4f1a-9caa-e57a4b5fc349
    CyRequest:
      type: object
      properties:
        algorithm:
          type: string
          description: Name of algorithm to run
          example: updatetablesexample
        data:
          $ref: '#/components/schemas/JsonNode'
        parameters:
          type: object
          additionalProperties:
            type: string
            description: "Optional parameters in simple map format arg: value"
          description: "Optional parameters in simple map format arg: value"
    CyServerStatus:
      type: object
      properties:
        status:
          type: string
          description: Status of server
          enum:
          - ok
          - error
        version:
          type: string
          description: Gets version of this service