Warning

API docs are outdated. Please contact us for details.

REST API¶

The PLynx REST API allows you to perform most of the actions with Graphs, Operations and Files. The API is hosted under the /plynx/api/v0 route on the PLynx server. For example, to list latest Graphs on backend server hosted at http://localhost:5005, make GET request: http://localhost:5005/plynx/api/v0/graphs.

Table of Contents

Authentication
List multiple Graphs
Get single Graph
Post Graph
Single action endpoints
List multiple Nodes
Get single Node
Post Node
Upload File
Modify existing Graphs
Working with a single Resource
Get state of the Master

Authentication ¶

User session should start with this endpoint. If a user if is verified, response will contain access and refresh tokens.

Endpoint	HTTP Method
`plynx/api/v0/token`	`GET`

Response Structure¶

Field Name	Type	Description
status	`STRING`	Status of the query. One of the following: `success` or `failed`
message	`STRING`	Extended status.
access_token	`STRING`	Short-term token.
refresh_token	`STRING`	Long-term token.

List multiple Graphs ¶

Endpoint	HTTP Method
`plynx/api/v0/search_graphs`	`POST`

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/plynx/checkouts/latest/docs/rest.rst, line 66)

Blank line required after table.

Get a list of Graphs. You can specify search parameters as a request body, for example:

{
   "per_page": 20,
   "offset": 0,
   "search":"author:default "
}

Request Structure¶

Parameter name	Type	Default value	Description
search	`STRING`	`""`	Search string. See plynx-internal-search-string for more details.
per_page	`INTEGER`	`20`	Number of instances returned by the query.
offset	`INTEGER`	`0`	Number of instances to skip.
status	`STRING` or `LIST`	`[]`	List of statuses. See Graph Running Status for more details.

Response Structure¶

Field Name	Type	Description
items	An array of Graph	All experiments.
total_count	`INTEGER`	Total number of graphs that meet the query.
status	`STRING`	Status of the query. One of the following: `success` or `failed`

Example¶

curl -X POST \
    'http://localhost:5005/plynx/api/v0/search_graphs' \
    -u default: -H "Content-Type: application/json" \
    -d '{"per_page":1, "search":"author:default"}'

Get single Graph ¶

Endpoint	HTTP Method
`plynx/api/v0/graphs/{graph_id}`	`GET`

Get a single Graph in Graph format.

Parameter graph_id is required.

When graph_id == "new" (i.e. curl 'http://localhost:5005/plynx/api/v0/graphs/new' -u default:) PLynx backend will generate a default empty Graph. Please note this new Graph will not be saved in the database. Use POST request instead plynx-rest-post_graph:

Response Structure¶

Field Name	Type	Description
data	Graph	Graph object.
resources_dict	plynx-internal-resources_dict	Dictionary of available resources types that come as plugins.
status	`STRING`	Status of the query. One of the following: `success` or `failed`

Example¶

curl 'http://localhost:5005/plynx/api/v0/graphs/5d1b8469705c1865e288a664' -u default:

Post Graph ¶

Endpoint	HTTP Method
`plynx/api/v0/graphs`	`POST`

This endpoint covers multiple actions with a Graph, such as saving, approving, generating code, etc. A single request can contain a sequence of actions that will be applied in the same order.

Note that some of the actions that require a change in the database, are not always permitted. For example when the user is not the original author of the Graph. In this case the Graph is considered as read only.

Data¶

Parameter name	Type	Description
graph	Graph	Graph object.
action	`LIST` of `STRING`	List of actions. See Actions for more details.

Actions¶

Action Name	Description	Permission limitations	Extra fields in response
SAVE	Save the graph. If the Graph with the same Id does not exist, it will be created.	Author must match the current user
APPROVE	Save the graph and execute it if it passes validation.	Author must match the current user	`validation_error`
VALIDATE	Check if the Graph passes validation, i.e. cycles detected, invalid inputs, etc.	Any User	`validation_error`
REARRANGE	Rearrange Nodes based on topology of the Graph.	Any User
UPGRADE_NODES	Replace outdated nodes with new versions	Any User	`upgraded_nodes_count`
CANCEL	Cancel currently running Graph.	Author must match the current user
GENERATE_CODE	Generate python API code that can recreate the same graph.	Any User	`code`
CLONE	Clone the graph and save it.	Any User	`new_graph_id`

Response Structure¶

Field Name	Type	Description
graph	Graph	Graph object.
url	`STRING`	URL.
message	`STRING`	Dictionary of available resources types that come as plugins.
status	`STRING`	Status of the query. One of the following: `success` or `failed` or `validation_failed`
validation_error (extra)	An array of plynx-internal-validation_error	If errors found on validation step.
upgraded_nodes_count (extra)	`INTEGER`	Dictionary of available resources types that come as plugins.
code (extra)	`STRING`	Resulting code

Single action endpoints ¶

Similarly to Actions, you can perform actions with existing Graphs. These POST-requests do not require json data. Backend will use existing Graph instead.

Endpoint	HTTP Method	Data
`plynx/api/v0/graphs/{graph_id}/approve`	`POST`	None
`plynx/api/v0/graphs/{graph_id}/validate`	`POST`	None
`plynx/api/v0/graphs/{graph_id}/rearrange`	`POST`	None
`plynx/api/v0/graphs/{graph_id}/upgrade_nodes`	`POST`	None
`plynx/api/v0/graphs/{graph_id}/cancel`	`POST`	None
`plynx/api/v0/graphs/{graph_id}/generate_code`	`POST`	None
`plynx/api/v0/graphs/{graph_id}/clone`	`POST`	None

Additional PATCH endpoint is available to update the Graph.

Endpoint	HTTP Method	Data
`plynx/api/v0/graphs/{graph_id}/update`	`PATCH`	JSON, required

Example¶

# Clone existing Graph
curl -X POST \
    'http://localhost:5005/plynx/api/v0/graphs/5d1b8469705c1865e288a664/clone' \
    -u default:
# {"status": "SUCCESS", "message": "Actions completed with Graph(_id=`5d1b8469705c1865e288a664`)", "graph": {"_id": "5d291e57713b286094d4ad85", "title": "hello world", "description": "Description", "graph_running_status": "CREATED", "author": "5d0686aa52691468eaef391c", "nodes": [{"_id": "5d27e3bd0f432b5e3693314c", "title": "Sum", "description": "Sum values", "base_node_name": "python", "parent_node": "5d27b8dd50e56dbbce063449", "successor_node": null, "inputs": [{"name": "input", "file_types": ["file"], "values": [], "min_count": 1, "max_count": -1}], "outputs": [{"name": "output", "file_type": "file", "resource_id": null}], "parameters": [{"name": "cmd", "parameter_type": "code", "value": {"value": "s = 0\nfor filename in input[\"input\"]:\n    with open(filename) as fi:\n        s += sum([int(line) for line in fi])\nwith open(output[\"output\"], \"w\") as fo:\n    fo.write(\"{}\\n\".format(s))\n", "mode": "python"}, "mutable_type": false, "removable": false, "publicable": false, "widget": null}, {"name": "cacheable", "parameter_type": "bool", "value": true, "mutable_type": false, "removable": false, "publicable": false, "widget": null}], "logs": [{"name": "stderr", "file_type": "file", "resource_id": null}, {"name": "stdout", "file_type": "file", "resource_id": null}, {"name": "worker", "file_type": "file", "resource_id": null}], "node_running_status": "CREATED", "node_status": "READY", "cache_url": "", "x": 190, "y": 143, "author": "5d0686aa52691468eaef391c", "starred": false}]}, "url": "http://localhost:3001/graphs/5d291e57713b286094d4ad85", "new_graph_id": "5d291e57713b286094d4ad85"}

# Change Title and Description
# Note "new_graph_id": "5d291e57713b286094d4ad85"
curl -X PATCH \
    'http://localhost:5005/plynx/api/v0/graphs/5d1b8469705c1865e288a664/update' \
    -u default: -H "Content-Type: application/json" \
    -d '{"title": "Custom title", "description":"Custom Description"}'

# Execute the Graph:
curl -X POST \
    'http://localhost:5005/plynx/api/v0/graphs/5d1b8469705c1865e288a664/approve' \
    -u default:

List multiple Nodes ¶

Note Files and Operations internally are represented as Nodes.

Endpoint	HTTP Method
`plynx/api/v0/search_nodes`	`POST`

Get a list of Nodes. You can specify search parameters as a request body, for example:

{
   "per_page": 20,
   "offset": 0,
   "search":"author:default "
}

Request Structure¶

Parameter name	Type	Default value	Description
search	`STRING`	`""`	Search string. See plynx-internal-search-string for more details.
per_page	`INTEGER`	`20`	Number of instances returned by the query.
offset	`INTEGER`	`0`	Number of instances to skip.
status	`STRING` or `LIST`	`[]`	List of statuses. See Node Status for more details.
base_node_names	`LIST` of plynx-internal-base_node	`[]`	List of base nodes. See plynx-internal-base_node for more details.

Response Structure¶

Field Name	Type	Description
items	An array of Node	Nodes (Operations and Files)
resources_dict	An array of plynx-internal-resources_dict	List of resources available in the platform.
total_count	`INTEGER`	Total number of nodes that meet the query.
status	`STRING`	Status of the query. One of the following: `success` or `failed`

Example¶

curl -X POST \
    'http://localhost:5005/plynx/api/v0/search_nodes' \
    -u default: -H "Content-Type: application/json" \
    -d '{"per_page":1, "search":"author:default"}'

Get single Node ¶

Endpoint	HTTP Method
`plynx/api/v0/nodes/{node_id}`	`GET`

Get a single Graph in Node format.

There are special cases when node_id is base_node_name, i.e. curl 'http://localhost:5005/plynx/api/v0/nodes/python' or curl 'http://localhost:5005/plynx/api/v0/nodes/bash_jinja2'. Backend will generate a default Operation.

Response Structure¶

Field Name	Type	Description
data	Node	Node object.
resources_dict	plynx-internal-resources_dict	Dictionary of available resources types that come as plugins.
status	`STRING`	Status of the query. One of the following: `success` or `failed`

Example¶

curl 'http://localhost:5005/plynx/api/v0/nodes/5d27b8dd50e56dbbce063449' -u default:

Post Node ¶

Endpoint	HTTP Method
`plynx/api/v0/nodes`	`POST`

This endpoint covers multiple actions with a Node, such as saving, approving, deprecating, etc.

Note that some of the actions that require a change in the database, are not always permitted. For example when the user is not the original author of the Node. In this case the Node is considered as read only.

Data¶

Parameter name	Type	Description
node	Node	Node object.
action	`STRING`	List of actions. See Actions for more details.

Actions¶

Action Name	Description	Permission limitations	Extra fields in response
SAVE	Save the Node. If the Node with the same Id does not exist, it will be created.	Author must match the current user
APPROVE	Save the Node and make accessible in Graphs if it passes validation.	Author must match the current user	`validation_error`
VALIDATE	Check if the Node passes validation, i.e. incorrect parameter values.	Any User	`validation_error`
DEPRECATE	Deprecate the Node. User will still be able to use it.	Author must match the current user
MANDATORY_DEPRECATE	Deprecate the Node mandatory. Users will no longer be able to use it.	Author must match the current user	`validation_error`
PREVIEW_CMD	Preview exec script.	Any User	`validation_error`

Response Structure¶

Field Name	Type	Description
node	Node	Node object.
url	`STRING`	URL.
message	`STRING`	Extended status.
status	`STRING`	Status of the query. One of the following: `success` or `failed` or `validation_failed`
validation_error (extra)	An array of plynx-internal-validation_error	If errors found on validation step.
preview_text (extra)	`STRING`	Resulting code.

Upload File ¶

This endpoint will create a new Node with type File. If you work with large files it is recommended to use an external file storage and Operation that downloads the file (i.e. S3).

Endpoint	HTTP Method	Data
`plynx/api/v0/upload_file`	`POST` or `PUT`	Forms, required

Form	Description
data	Binary data of the file.
title	Title of the file
description	Description of the file
file_type	Type, i.e. file, csv, image, etc.

Example¶

curl \
    -X POST \
    'http://localhost:5005/plynx/api/v0/upload_file' \
    -u default: \
    -H "Content-Type: multipart/form-data" \
    -F data=@/tmp/a.csv \
    -F title=report \
    -F description=2019 \
    -F file_type=csv
    -F node_kind=basic-file

Modify existing Graphs ¶

Endpoint	HTTP Method	Data
`plynx/api/v0/graphs/{graph_id}/nodes/list_nodes`	`GET`	None
`plynx/api/v0/graphs/{graph_id}/nodes/insert_node`	`POST`	node_id: required. x: optional. Default: 0. y: optional. Default: 0.
`plynx/api/v0/graphs/{graph_id}/nodes/remove_node`	`POST`	node_id: required.
`plynx/api/v0/graphs/{graph_id}/nodes/create_link`	`POST`	from: required. Type: Object. Output node description. from.node_id: required. from.resource: required. Name of the Output to: required. Type: Object. Input node description. to.node_id: required. to.resource: required. Name of the Input
`plynx/api/v0/graphs/{graph_id}/nodes/remove_link`	`POST`	from: required. Type: Object. Output node description. from.node_id: required. from.resource: required. Name of the Output to: required. Type: Object. Input node description. to.node_id: required. to.resource: required. Name of the Input
`plynx/api/v0/graphs/{graph_id}/nodes/change_parameter`	`POST`	node_id: required. parameter_name: required. parameter_value: required.

Example¶

curl -X POST 'http://localhost:5005/plynx/api/v0/graphs/5d292406713b286094d4ad87/nodes/insert_node' \
    -u default: -H "Content-Type: application/json" \
    -d '{"node_id": "5d2d4b1dc36682386f559eae", "x": 100, "y": 100}'

curl -X POST 'http://localhost:5005/plynx/api/v0/graphs/5d292406713b286094d4ad87/nodes/remove_node' \
    -u default: -H "Content-Type: application/json" \
    -d '{"node_id": "5d27e3bd0f432b5e3693314c"}'

curl -X POST 'http://localhost:5005/plynx/api/v0/graphs/5d292406713b286094d4ad87/nodes/create_link' \
    -u default: -H "Content-Type: application/json" \
    -d '{"from": {"node_id": "5d2fbdf3373d3b7ce6e69043", "resource": "out"}, "to": {"node_id": "5d3081ea99d54c7b6b8ff56b", "resource": "input"}}'

curl -X POST 'http://localhost:5005/plynx/api/v0/graphs/5d292406713b286094d4ad87/nodes/change_parameter' \
    -u default: -H "Content-Type: application/json" \
    -d '{"node_id": "5d30b7eb88fb6a42caf0c565", "parameter_name": "template", "parameter_value": "abc"}'

Working with a single Resource ¶

This endpoint is a proxy between the client and internal PLynx resources.

WARNING: try to avoid calling this endpoint without “preview” argument set to True. Currently PLynx supports multiple data storages and is not optimized for a particular one. It will be fixed in the future versions, exposing additional endpoints.

Endpoint	HTTP Method
`plynx/api/v0/resources/{resource_id}`	`GET`

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/plynx/checkouts/latest/docs/rest.rst, line 663)

Blank line required after table.

Additional arguments to the endpoint:

Argument	Type	Description
`preview`	`BOOLEAN`	Preview flag (default: false)
`file_type`	`STRING`	One of the plugins. See plynx-internal-file-types for more details.

Get state of the Master ¶

When Master is running, it periodically syncs its state with PLynx database. Use this endpoint to access it. See See plynx-internal-master_state.

Endpoint	HTTP Method
`plynx/api/v0/master_state`	`GET`

Example¶

curl 'http://localhost:5005/plynx/api/v0/master_state' -u default: