Specification for Service‐based App in Cytoscape Web (draft v2) - cytoscape/cytoscape-web GitHub Wiki
September 30, 2024
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.
Workflow diagram of a service-based app. Green bordered boxes are client-side functions in Cytoscape Web.
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
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:
- The configuration file of Cytoscape Web.
- The user's account profile.
- 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
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
-
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.
-
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 }
-
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" }
-
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 -
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.
-
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