Trying Automation

There are a number of ways for you to try out Cytoscape Commands and Functions without actually having to write a script or program.

This section explains how to access apps' automation features in using various methods:

• Cytoscape's Swagger documentation
• A web browser
• A REST client

For accessing Commands and Functions through scripts, see Cytoscape Automation for Script Writers.

Execution Requirements

To access Commands and Functions, you must first do the following:

1. Start Cytoscape. The default REST port is 1234. If you prefer a different port, start Cytoscape with the -R command line parameter followed by the port you prefer (normally './cytoscape.sh -R 1234' or './cytoscape.exe -R 1234').
2. Using the Cytoscape App Manager, ensure that the CyREST app is up to date -- new releases frequently appear in the app store.
3. Use the App Manager to install any apps implementing Functions or Commands you may want to call.

Accessing through Cytoscape's Swagger UI

Cytoscape's Swagger UI provides an excellent environment for discovering Function and Command documentation and trying a Function or Command directly.

Use the Help --> Automation menu to choose between two different APIs:

• Functions are available through the CyREST API menu item.
• Commands are available through the CyREST Command API menu item.

(Commands are also available through Cytoscape's Command Tool, though with a different user interface.)

Swagger gives you access to documentation on path parameters, query parameters, results and contextual information. It also allows you to frame and execute Function and Command calls directly from the Swagger page. For example:

Experiment: See simple CyREST-based Cytoscape access via Swagger:

1. Use Cytoscape's Help --> Automation --> CyREST API menu to show the CyREST Swagger page in a browser.
2. Choose REST Service and then GET /v1.
3. The browser should display the documentation page for the server status API.
4. Click the Try it out! button to execute the GET /v1 function and see its response.

Accessing through a Web Browser

HTTP GET operations (i.e., Commands and some Functions) are very easy to execute through a web browser (e.g., Google Chrome) as they require no message body to be included. Any GET-based operation can be requested by entering its path in the browser's URL area (e.g., http://localhost:1234/v1/). To find a list of existing operations and paths, you can explore the Swagger UI.

Experiment: See simple CyREST-based Cytoscape access via a browser:

1. Start Cytoscape and a web browser.
2. On the browser address bar, enter http://localhost:1234/v1/ CyREST operation.
3. The browser should display Cytoscape information similar to:

Though this method of testing can be convenient for quick tests, it has important limitations. HTTP operations outside of GET (e.g., POST, PUT, DELETE, PATCH) can require message bodies and might not be possible to access as intended through a browser. In addition, browsers normally display HTML data by default, and in some cases may not show Function or Command results of other types (e.g., plaintext or JSON).

Accessing through a REST Client

REST clients allow fine control over operation access, allowing users to set HTTP command (e.g., GET, PUT), message bodies, path parameters, query parameters, HTTP headers, etc.

Simple command-line clients, such as curl allow simple, command line access to REST, and may already be included in your operating system.

Some browsers accept plugins, such as Advanced REST Client, that implement a full-featured REST testing environment that allows all HTTP operations.

Dedicated applications such as Insomnia are also available.

Each tool has unique features and usage and provide valuable alternatives when experimenting with Cytoscape Automation.

Examples

Below are some simple examples of REST operations that can be used to try out Cytoscape Automation.

Get data from Cytoscape (GET)

• Get all networks as a list of SUIDs

GET http://localhost:1234/v1/networks

• Get Visual Style names

GET http://localhost:1234/v1/styles

• Get Visual Style named Directed as JSON

GET http://localhost:1234/v1/styles/Directed

• GET list of layout algorithms

GET http://localhost:1234/v1/apply/layouts

• Apply force-directed layout to network with SUID 53

GET http://localhost:1234/v1/apply/layouts/force-directed/53

Create new objects in Cytoscape

• Send network and tables as JSON
  • Network to be sent:

{
      "data": {
            "name": "my network 1"
      },
      "elements": {
            "nodes":[...],
            "edges":[...]
      }
}

POST http://localhost:1234/v1/networks

Update existing data

• Add new nodes to existing network with SUID 52

PUT http://localhost:1234/v1/networks/52

Delete existing objects

• Delete all networks in current session

DELETE http://localhost:1234/v1/networks

• Delete a network with SUID 52

DELETE http://localhost:1234/v1/networks/52

• Delete a node with SUID 1200

DELETE http://localhost:1234/v1/networks/52/nodes/1200