Specification for Service‐based App in Cytoscape Web (draft v2)

September 30, 2024

Motivation

This specification outlines the necessary interface for implementing and registering a service-based app within Cytoscape Web. It enables users to integrate new functions, such as new layout methods, into the Cytoscape ecosystem and activate these services in Cytoscape Web.

Design Overview

Workflow diagram of a service-based app. Green bordered boxes are client-side functions in Cytoscape Web.

Download the PowerPoint file

When Cytoscape Web sends a task request to the backend service, the request body should have this data structure

The result of a request should have this data structure

Client Side

On the client side, Cytoscape Web utilizes an apps attribute to determine the service-based apps to be loaded. Entries in this object are used to generate new menu items linked to registered services.

The configuration object is located in:

1. The configuration file of Cytoscape Web.
2. The user's account profile.
3. The workspace profile.

Configurations lower in this list override those higher up.

The value of apps is a list of AppDefinition objects. Each AppDefinition object has the following structure:

{
  "url": string
}

Fields:

• url: The app's URL (service location or path to the client app bundle). For example: "https://cd.ndexbio.org/cy/updatetablesexample" with a swagger page showing usage at https://cd.ndexbio.org/cy/

Reference Interface:
AppDefinition.ts

Service Side

A service-based app may have any number of endpoints. To register with Cytoscape Web, it must implement the endpoints outlined in this spec. Each endpoint must include the specified data field in its response, with additional attributes permissible but ignored by Cytoscape Web.

A prototype Open API yaml file

1. Metadata: Provides service name, description, parameters, and validation methods.

   Method	GET
   Path	/
   Return Code	Success: 200 (OK)

                  Error: 400 (Bad Request) or 500 (Internal Server Error)  |
   

   Response Data Structure:

   {
     "serviceInputDefinition": Object (SelectionMethod),
     "cyWebActions": [string],
     "cyWebMenuItem": Object (RootMenu),
     "name": string,
     "description": string,
     "author": string,
     "citation": string,
     "version": string,
     "parameters": [
       Object (Parameter)
     ]
   }

   See Service Metadata for more information.

2. Service Status: Indicates service running status.

   Method	GET
   Path	/status
   Return Code	Success: 200 (OK)

                  Error: 503 (Service Unavailable) or 500 (Internal Server Error) |
   

   Response:

   {
     "status": "ok",
     "version": "1.0.0",
     "numberOfRunningTasks": 6
   }

3. Task Submission: For client request submission.

   Method	POST
   Path	/
   Request Header	Content-Type: application/json
   Return Code	Success: 202 (Accepted)

                   Error: 400 (Bad Request) or 500 (Internal Server Error) |
   

   Request Body:

   {
     "parameters": { 
                     "<Parameter display Name>": "value1", 
                     "param2": "value2" // Additional parameters
                   }, 
     "data": "cx2" // Data object constructed according to the selectedData attribute
   }

   NOTE: For flag only parameters such as checkBox just set value of parameter to empty string ""

   Example:

     "parameters" : { "Configuration Model": "RBER", }

   Response:

   {
     "id": "261fb9b7-75af-4f1a-9caa-e57a4b5fc349"
   }

4. Task Status: Returns status of a specific task.

   Method	GET
   Path	/<taskID>/status
   Return Code	Success: 200 (OK)

                   Error: 404 (Not Found) or 500 (Internal Server Error) |
   

   Response:

   {
      "progress": number // 0 - 100 where 100 means complete
      "status": string // One of the following: submitted, processing, complete, failed
      "result": null
   }

   See Task Result Response for more information, just note result will be set to null for this endpoint

5. Task Result: Provides status and result of a specific task.

   Method	GET
   Path	/<taskID>
   Return Code	Success: 200 (OK)

                   Error: 404 (Not Found) or 500 (Internal Server Error) |
   

   Response:

   {
      "id": string,
      "status": string,
      "message": string,
      "progress": number,
      "result": object
   }

   See Task Result Response for more information.

6. Task Deletion: Deletes the specified task. If a task is still running when a delete request is received, the server should stop the task and delete it.

   Method	DELETE
   Path	/<taskID>
   Return Code	Success: 204 (No Content)

                   Error: 404 (Not Found) or 500 (Internal Server Error) |
   

---

Prototype service up at: https://cd.ndexbio.org/cy/cytocontainer/v1/updatetablesexample

---