Tutorial on interacting with GraphSpace



Logging In

The welcome page greets a user when the user visits GraphSpace. We assume that the user has already created an account and uploaded graphs via the upload page or the RESTful API.





The user logs in and is provided a link to the list of graphs that the user can access.




Clicking on the link titled "Graphs" takes the user to a page that lists the graphs accessible by the user. In this example, this user owns 33 graphs and can access public graphs. No graphs are shared with this user.



Searching within a Single Graph


The same search interface greets the user on the page for this graph, which allows the user to add more search terms for nodes (Wnt in this example).



The user can also add search terms for edges ("Wnt:Fzd" in this example). Since the user has selected the "similar" option for the search, any edge whose tail node identifier or label contains "Wnt" and whose head node identifier or label contains "Fzd" matches the query.




By selecting an "Exact" option, the user can perform a new search for nodes that are an exact match to the query, which is "BAMBI" in this figure.




Figure 9: GraphSpace also supports exact searches for edges.


Interacting with a Graph

As its name suggests, the "Graph details" panel displays information about the entire graph, e.g., a legend of node and edge shapes and colors.



Clicking on a node pops up a panel with information on that node.




Clicking on a edge pops up a panel with information on that edge. The information that appears in "Graph Details" and the pop-up panels must be included in the JSON for the graph uploaded by the user using the RESTful API.



A user can export a graph in PNG format and view the JSON string for the graph. GraphSpace does not support any other export formats since it relies on Cytoscape.js for this functionality, which implements only export to PNG format.

Automatic and Manual Layouts

The layout panel for a graph displays two alternatives: automatic and manual.



Clicking on the first choice reveals the name of layout algorithms supported by GraphSpace through its use of Cytoscape.js.



Clicking on the "Manual" tab shows that there are two "Private" layouts, meaning that the user has not yet shared them with any other user. The user has created them in earlier sessions by manually modifying the positions of nodes and edges created by some automatic layout algorithm and saving the layout. The icons next to each layout name provide (i) a direct link to this layout, (ii) allow the user to change its name, (iii) share it with other users who have access to this graph, (iv) delete this layout, and (v) make it the default layout, i.e., instruct GraphSpace to display this layout whenever a user visits the page for this graph.



The user selects to view the layout titled "manual-top-to-bottom".



Description of GraphSpace's Interface and Features

This page provides a detailed description of GraphSpace's features and how a user may interact with it in a browser. We document the REST API that allows registered users to programmatically interact with GraphSpace in the Programmer's Guide.

Terminology

This section describes GraphSpace concepts and terms that are used throughout the documentation.

Anonymous vs. Registered user

An anonymous user is anyone that is using GraphSpace without being logged in. An anonymous user does not have access to the REST API and may not be a member of a group. Such a user may upload graphs anonymously via a web interface. We will delete graphs that are uploaded after 30 days.

A registered user is anyone that is logged into GraphSpace. By logging into GraphSpace, a user has full access to the REST API and is allowed to be a member of groups. Graphs uploaded by a registered user will remain in that user's account unless explicitly deleted by the user.


Graph visibility: Private, Shared, or Public

The visibility of a graph uploaded by a registered user can have one of three states: private, shared, or public. The visibility of a graph controls who can view the graph and interact with it upon visiting the URL associated with that graph.

Private
When a registered user uploads a graph to GraphSpace either through the REST API or through the web interface, its visibility is private, i.e., only the graph owner (the user who uploaded it) can view it.
Shared
A graph owner may share a graph with one or more groups. At this point, the graph's visibility is shared, i.e., all members of these groups may view the graph.
Public
A graph owner may make the graph public through the REST API.

When an anonymous user uploads a graph, it is by default a public graph, i.e., it is accessible to any user who visits GraphSpace and knows the URL of the graph.


Groups

A group is a collection of GraphSpace users. For example, if there are multiple researchers who are collaborating a project, a group may be created containing all of them. Another use case for a group is for all students registered in a network biology course. Once a GraphSpace user becomes a member of a group, the user may share any graph that he/she owns or a layout of such a graph with the group. Only members of that group will be able to access the graph. A user may share a graph will multiple graphs. Conversely, a user may be a member of multiple groups but share a graph only with some of these groups.

A group owner is the creator of the group. Any GraphSpace user can create a group by visiting the Groups page and clicking the "Create group" button. The group owner may
  • Invite any GraphSpace user that has an account to be a member of their group.
  • Remove any member from the group.
  • Unshare any graph that has already been shared by the members of the group
A group member is a user who is a part of a group. (A group owner is trivially a member of the group.) A group member may
  • Share a graph owned by him or her with a group.
  • Unshare a previously shared graph.
  • Share a layout for a previously shared graph.
  • Unshare a previously shared layout.
The Groups page provides access to all the groups owned by the user (by clicking the link "Owner of") as well as the groups of which the user is a member (via the link "Member of"). The user will have the option to delete a group (if the user wowns it) or to unfollow a group (if the user is a member).

Clicking on the name of a group will open a new page that lists all the graphs in that group. This page will also contain a panels to search for nodes and edges in graphs belonging to that group and a panel to search for graphs in that group that match specific tags. If the user owns the group, there will be an interface to add or delete members. If the user is a member of group, the user can only see who are the other members of the group. Notes:
  • Users must have GraphSpace accounts and be logged in in order to access group functions.
  • By design, groups are private, i.e., a GraphSpace user does not have access to the names of groups of which the user is not a member.
  • GraphSpace does not have a mechanism wherein a user may request to become a member of a group. All memberships must be managed by private communication.

Upload graphs

GraphSpace provides two methods to upload graphs: through the REST API or through the web interface.

Via the REST API

This approach allows one to be more flexible and utilize all of the CSS features by specifically referencing them in the JSON for the graph. Please refer to the Programmer's Guide for more information.


Via the Web Interface

As an alternative to the REST API for uploading a graph, we provide a simple web interface for uploading individual graphs. We support the following types of graphs:

  • Graphs that follow the GraphSpace JSON format. As explained in the GraphSpace JSON reference, we have extended the JSON format used by Cytoscape.js. These files must use the .json extension.
  • Graphs that a user of Cytoscape (v3.1 or later) can export into a different JSON format, which we call "cyjs". Please follow these instructions to export your Cytoscape graph to this format. These files must use the .cyjs extension. Note: Files using the .cyjs format may only be uploaded via the web interface.

If a user has an account and is logged in, this interface will upload the graph directly into the user's account, much like using the REST API. If a user does not have an account or is not logged in, this upload functionality will provide a unique URL through which the user may interact with the graph represented by the uploaded file. Note: After 30 days, we will delete all graphs that are uploaded for unregistered users of GraphSpace.


Interact with graphs

We will use the following public graph as a running example. When viewing a graph, you will notice several panels to the right. Some of these panels may be closed. Clicking on an individual panel will reveal information within it.




Node and Edge Popups

Each node or edge in a graph may have information embedded in it. Clicking on a node or edge will colour that element's border color red. If the clicked node/edges contains information (see JSON reference), this information will appear in a pop-up box; otherwise, no pop up will be shown. If this information is formatted in HTML, GraphSpace will interpret it appropriately. The image below shows an example of the information that is contained inside of a node CCT6.




Graph Details Panel

This panel contains information describing the graph, e.g., a legend.



Search Panel

This panel provides an interface that allows the user to find nodes/edges that match search terms. See Elements within a graph for information on query semantics. If one or more nodes or edges matches the query, GraphSpace generates a link above the search bar. Visting this link will display the graph with all the nodes/edges matching the search terms highlighted. The user can share this URL with other GraphSpace users who can access this graph.


Export Panel

Through this panel, a user can export an image of the current layout of the graph as a PNG file. The JSON option allows a user to see the the JSON representation of the graph.


Owner Panel

This panel shows the GraphSpace user to whom the graph belongs.


Sharing Panel

This panel displays all the groups with which the graph is shared. If the user is the owner of the graph, the panel will also provide an interface to allow the user to share this graph with all the groups of which the user is a member.


Layouts Panel

By a "layout," we mean an assignment of x- and y- coordinates to each node in a graph that allows it to be drawn on the screen. The user may move nodes manually to manipulate the layout. This panel provides access to several functions:
  1. A powerful layout editor.
  2. Multiple algorithms to layout a graph.
  3. Ability to save layouts.
  4. Abilily to access saved layouts later and share them with other users. Note: a user must be registeted with GraphSpace in order to save and share layouts.
In this section, we focus on the last three features, with the layout editor described separately.

Auto Layouts

Manual Layouts

Automatic layouts
The 'Auto' tab allows the user to apply several automatic layout algorithms available through Cytoscape.js. Note that GraphSpace may expose only some of the algorithms available in Cyotscape.js.
Saving layouts
Any registered user who can access the graph may save the current layout by clicking the "Save layout" button in the "Layout" panel. A pop-up will allow the user to enter the name of the current layout. GraphSpace will prevent the user from using a name that is already associated with another layout previously saved by the user. The user may save a layout that is generated automatically, through the layout editor, or by manual manipulation of node positions.
Accessing saved layouts
The 'Manual' tab provides access to saved layouts. Clicking on this tab will show two sets of layouts: 'Private' and 'Shared'.
  • Private layouts are those previously created by the user but not shared with any other users. When the user clicks on one of the saved layouts, GraphSpace displays the following options: (i) a direct link (URL) to this layout, (ii) change the name of the layout, (iii) share this layout with other users who have access to this graph, (iv) delete this layout, and (v) make it the default layout, i.e., instruct GraphSpace to display this layout whenever a user visits the page for this graph. Note: A user may share the layout only if the graph is shared with at least one group.
  • Shared layouts are those created by the user or by some other user and also shared with the groups that can access this graph. When the user clicks on one of the saved layouts, GraphSpace displays the following options: (i) a direct link (URL) to this layout, (ii) change the name of the layout, (iii) unshare this layout with other users who have access to this graph, and (iv) make it the default layout, i.e., instruct GraphSpace to display this layout whenever a user visits the page for this graph.

Layout Editor


GraphSpace provides powerful tools for the selection, movement, and organization of multiple nodes in a graph. The user can activate this functionality by clicking the Use Layout Editor button in the Layouts panel. Clicking this button takes a user of GraphSpace to a simplified view of the graph that de-emphasizes edges and hides node names. The Start Tour button walks the user through all the features provided in the tool pallette. The Exit layout editor button gives a user the option to save the current layout and/or go back to the original view of the current graph. In the layout editor, the user may wield the tool pallette on the right hand side to quickly re-arrange the structure of the graph. The picture below shows the simplified version of the graph seen throguhout this guide.

The Select section allows the user to choose nodes in the graph based on two types of properties: Shape and Color.

The Shape section allows a user to select all nodes that have any of the selected shapes. For example, if a user wishes to select all nodes that are rectangles or ellipses, he/she will select both "Ellipse" and "Rectangle" in the tool pallete.

The Color section allows a user to select all nodes that are any of the selected colors. For example, if a user wishes to select all nodes that are yellow or green, he/she will select both yellow and green.

If a user wants to select all nodes that are rectangles AND are yellow, they would select rectangles from the Shape section and yellow from the Color section.

A user may click on the Unselect All Nodes button to reset all selections. The Undo and Redo buttons allow the user to undo or repeat all actions, including selection and the arrange functions described below.

The Arrange section allows a user to arrange all selected nodes into regions of different shapes. The following picture shows the arrangements of selected nodes that users may construct by clicking different buttons in this section.

Open Circle

Closed Circle

Open Rectangle

Closed Rectangle

Vertical Line

Horizontal Line

Pinch

Expand

Filter Nodes and Edges Panel

Graph algorithms may output networks where nodes and edges can be ranked, e.g., by path index or by weight/score. GraphSpace allows each node and edge to have an integer-valued attribute called k that specifies the rank of the node or the edge. For any network that contains this attribute (and only for such networks), GraphSpace displays the "Filter nodes and edges" panel with two sliders. The user can adjust these sliders to view only those nodes and edges with values of k below a threshold. This interface element allows the user to unveil the network gradually in real time and gain intuition about how the network expands or contracts as this threshold changes.
Current rank
Changing the value in this slider hides all nodes and edges whose k values are less than or equal to the value in the slider. The possible values in this slider range from 1 to the value in the bottom slider labeled "Maximum rank". The images below show a user stepping through a graph using this slider. For example, changing the value from 8 to 10 revealed the red node and the edge connecting it to the blue node.
Maximum rank
Changing the value in this slider hides nodes and edges as for the top slider. Moreover, for automatically generated layouts, GraphSpace will lay out afresh the corresponding subgraph of that network. Decreasing the value of this slider in conjunction with the redraw is especially useful for viewing large or dense networks using automatic algorithms. For saved layouts, this slider only hides the relevant nodes and edges without changing the coordinates of the displayed elements.

Changing the value in the bottom slider also automatically controls the range in the top slider. Hence, the two sliders can be used in combination, e.g., to restrict the view to the top 50 nodes and edges in the graph (select "50" in the bottom slider) and then to step through the first 50 nodes and edges (vary the top slides from "1" to "50").


Share graphs

A user may share a graph and its layouts with groups to which the user belongs.

Sharing graphs with group(s)

There are two ways to share a specific graph owned by the user: the REST API and the Sharing Panel. A user may share a graph with multiple groups. In order to share a graph, the user must own it. In addition, the user must be a member or the owner of the group he/she wants to share the graph with. Sharing a graph allows all the members in the group to access the graph. Un-sharing a graph from a graph means that no one else in the group will be able to access that graph anymore.


Sharing layouts with group(s)

Similar to a graph, a layout may also be shared with a group. In order for a layout to be shared with a group, the graph must already be shared with the group. Currently, the only way to share a layout is through the Layouts Panel. Initially, only the creator of a saved layout is allowed to access it. Note that a layout may be created by a user who is not the owner of the graph, as long as the layout creator can access the graph (because the owner has shared it). Sharing a layout changes its access as follows:

Public graphs
The layout is also publicly available, i.e., to all users of GraphSpace.
Shared graphs
The layout is accessible to every user who is a member of a group with which the graph is shared, as long as the layout creater is also a member of that group.


GraphSpace allows the user to search at two different levels. First, the user may visit the Graphs page and search for all graphs (owned by or shared with the user or public) that match the query. Second, the user may visit a specific graph to find nodes and edges within it that match a query.


Semantics

GraphSpace supports simple search semantics:
Node
Provide the node's label or id, e.g., AKT1
Edge
Use the syntax tail:head, where tail is the name of the source node and the head is the name of the target node, e.g., Wnt:Fzd.
Multiple nodes/edges
In order to search for multiple terms, simply seperate each search term with a ",". For example: AKT1, AKT3, CTNNB1.
Similar or Exact

Elements within a graph

GraphSpace allows a user to search for a nodes and edges that are inside a graph. If a search term is found in the graph it is highlighted in the graph. Multiple nodes and edges may be searched for within a graph by seperating each node/edge with a ",".

For example, if a user searched for the node 'TEM1', then the node will look like this:


TEM1 before searching

TEM1 after searching



If a user wants to search for edge connection from TEF4 to TEM1, they can do so with the following search command: TEF4:TEM1. The edge will look like this:

Before searching for edge

After searching for edge

The Similar option under the search bar allows one to search for all elements within a graph which may have the search term as part of its value. For example, if there are two nodes CDC5 and CDC55 and the user does a similar search with the term 'CDC', then both CDC5 and CDC55 will be highlighted.

The Exact option under the search bar allows one to search for all elements within a graph that are identical to the search term. If there are two terms CDC5 and CDC55 and the user does an exact search with the term 'CDC5', only CDC5 will be highlighted. Note: If the user had searched for the term 'CDC', nothing would have been highlighted since there are no nodes in our example graph which have CDC as their entire value.

Note:If there are mulitple search terms, all elements that are contained within the graph that is being searched on will be highlighted.


Graphs that contain elements

The Similar option under the search bar allows one to search for all graphs that may contain that word in the graph itself. This option will return all the graphs that may have a node which contains parts of the term(s) being searching, graphs that may contain part of the searched term in its name, as well as if there are edges which contain part of the searched term(s).

The Exact option under the search bar allows one to search for all graphs that have exactly what is being searched for. Graphs returned from this option may have a node, graph name, or an edge which is identical to the searched term(s).

To search for graphs that match a graph name, simply type the name or a part of the name of the graph

To search for nodes, type the content inside of the node (text that is contained inside of a node)

To search for edges, search using the following syntax [tail: head] where tail is the name of the node where the arrow is coming from and head is the name of the node that the arrow is point to. For example, to search for the edge that connects YEF3 to SIR2, type YEF3:SIR2. All graphs that contain this edge will be presented to the user.

If searching for multiple values, separate all individual search terms with commas. Ex: AKT1, AKT3, JUN

Note:If there are multiple search terms (and/or tag terms), all graphs that are returned WILL match all of these terms. All graphs that are returned by the searches of a node and/or an edge will have all searched terms highlighted inside the graph.


Organize Graphs Using Tags

To aid the organization of graphs, GraphSpace uses the concept of tags. Each graph may have any number of tags. A tag is a useful mechanism for grouping a set of graphs, e.g., all the graphs that a user may desire to make public upon the publication of a paper. All tags associated with a graph must be defined in the metadata for the graph. Hence, tags may be specified only when a user uploads graphs using the REST API. A user can search for graphs that match a tag. To search for multiple tags, simply separate them with commas. Currently, the user must know the exact name of the tag.

Note: Tags provide a level of organization that are orthogonal to groups. Groups are intended to organize collaborating users of GraphSpace while tags are used to collect graphs.

This page describes the RESTful API provided by GraphSpace for uploading and managing your graphs. This API offers the following advantages:
  • A user with an account can write software to upload several graphs in an automated manner.
  • In the JSON for every uploaded graph, the user may specific the graph’s names, details about it, and information on every node and edge.

In order to fully utilize the features of this RESTful API, you must have an account on GraphSpace.

Prerequisites

To execute the examples from the command line you will need an HTTP client. On Debian systems you can install one by running

sudo apt-get install curl

REST API Basics

All of the GraphSpace API documentation adhere to the following semantics.

Anything in "[]" specifies a variable. For example, [email] means use GraphSpace account (email) in place of [email] in the request.

Example GET graph request in the documentation is:

curl -X POST "http://localhost:8000/api/users/[email]/graph/get/[graphname]/" -F "username=[email]" -F "password=[password]"; echo

The same GET graph request for a graph named "example_graphname" and a GraphSpace email of "example@example.com" with password "example_password" would be:

curl -X POST "http://localhost:8000/api/users/example@example.com/graph/get/example_graphname/" -F "username=example@example.com" -F "password=example_password"; echo

In general, API calls using this REST API will have a "StatusCode" property. This property adheres to the usual REST API status codes.

REST API calls

Below is a list of the different REST API calls.


Graphs

JSON Reference

This section details the structure of the JSON that all graphs inserted into GraphSpace should follow. Any deviation from this schema may result in GraphSpace rejecting the graph or problems in rendering the graph. For the sake of completeness, we have copied the description of several of the node and edge attributes directly from the CytoscapeJS documentation. We thank them for the excellent documentation of their framework.

A properly formatted JSON for a graph in GraphSpace contains the following structure:

{
    "graph": {
        "nodes": [],
        "edges": []
    },
    "metadata": {
        "title": "",
        "description": "",
        "tags": []
    }
}

Node

This table lists all the properties that GraphSpace supports for a Node element.

Property Description
id A unique id representing the node. (REQUIRED)
content The text that is displayed inside of the node.
popup A string that will be displayed in a popup window when the user clicks the node. This string can be HTML-formatted. (This attribute is specific to GraphSpace.)
k An integer index for this node. GraphSpace uses this attribute when the user seeks to step through the nodes and edges of the graph. (This attribute is specific to GraphSpace.)
background_color The background color of the node. It may be the names of colors or hexadecimal values of the colors.
height The height of the node.
width The width of the node.
shape The shape of the node. May be: rectangle, roundrectangle, ellipse, triangle, pentagon, hexagon, heptagon, octagon, star, diamond, vee, or rhomboid.
background_blacken Blackens the node's body for values from 0 to 1; whitens the node's body for values from 0 to -1.
background_opacity The opacity level of the node's background color.
border_width The size of the node's border.
border_style The style of the node's border; may be solid, dotted, dashed, or double.
border_color The color of the node's border.
border_opacity The opacity of the node's border.
background_image The URL that points to the image that should be used as the node's background. PNG, JPG, and SVG are supported formats. You may use a data URI to use embedded images, thereby saving a HTTP request.
background_image_opacity The opacity of the background image.
background_width Specifies the width of the image. A percent value (e.g. 50%) may be used to set the image width relative to the node width. If used in combination with background-fit, then this value overrides the width of the image in calculating the fitting — thereby overriding the aspect ratio. The auto value is used by default, which uses the width of the image.
background_height Specifies the height of the image. A percent value (e.g. 50%) may be used to set the image height relative to the node height. If used in combination with background-fit, then this value overrides the height of the image in calculating the fitting — thereby overriding the aspect ratio. The auto value is used by default, which uses the height of the image.
background_fit Specifies the width of the image. A percent value (e.g. 50%) may be used to set the image width relative to the node width. If used in combination with background-fit, then this value overrides the width of the image in calculating the fitting — thereby overriding the aspect ratio. The auto value is used by default, which uses the width of the image.
background_repeat Whether to repeat the background image; may be no-repeat, repeat-x, repeat-y, or repeat.
background_position_x The x position of the background image, measured in percent (e.g. 50%) or pixels (e.g. 10px).
background_position_y The y position of the background image, measured in percent (e.g. 50%) or pixels (e.g. 10px).
background_clip How background image clipping is handled; may be node for clipped to node shape or none for no clipping.
color The color of the text displayed inside the node.
font_family A comma-separated list of font names to use on the node text.
font_size The size of the node text.
font_style A CSS font style to be applied to the node text.
font_weight A CSS font weight to be applied to the node text.
text_transform A transformation to apply to the label text; may be none, uppercase, or lowercase.
text_wrap A wrapping style to apply to the label text; may be none for no wrapping (including manual newlines: \n) or wrap for manual and/or autowrapping.
text_max_width The maximum width for wrapped text, applied when text-wrap is set to wrap. For only manual newlines (i.e. \n), set a very large value like 1000px such that only your newline characters would apply.
edge_text_rotation Whether to rotate edge labels as the relative angle of an edge changes; may be none for page-aligned labels or autorotate for edge-aligned labels. This works best with left-to-right text.
text_opacity The opacity of the label text, including its outline.
text_outline_color The color of the outline around the element's label text.
text_outline_opacity The opacity of the outline on label text.
text_outline_width The size of the outline on label text.
text_shadow_blur The shadow blur distance.
text_shadow_color The color of the shadow.
text_shadow_offset_x The x offset relative to the text where the shadow will be displayed, can be negative. If you set blur to 0, add an offset to view your shadow.
text_shadow_offset_y The y offset relative to the text where the shadow will be displayed, can be negative. If you set blur to 0, add an offset to view your shadow.
text_shadow_opacity The opacity of the shadow on the text; the shadow is disabled for 0 (default value).
text_background_shape The shape to use for the label background, can be rectangle or roundrectangle.
text_border_width The width of the border around the label.
text_border_style The style of the border around the label; may be solid, dotted, dashed, or double.
text_border_color The color of the border around the label.
min_zoomed_font_size If zooming makes the effective font size of the label smaller than this, then no label is shown.
text_halign The vertical alignment of a label; may have value left, center, or right.
text_valign The vertical alignment of a label; may have value top, center, or bottom.

Edge

This table lists all the properties that GraphSpace supports for an Edge element.

Name Description
source The id of the node where the edge is coming from. (REQUIRED)
target The id of the node where edge is going to. (REQUIRED)
popup A string that will be displayed in a popup window when the user clicks the edge. This string can be HTML-formatted. (This attribute is specific to GraphSpace.)
k An integer index for this edge. GraphSpace uses this attribute when the user seeks to step through the nodes and edges of the graph. (This attribute is specific to GraphSpace.)
width The width of an edge's line.
line_color The color of the edge's line.
line_style The style of the edge's line; may be solid, dotted, or dashed.
source_arrow_color The color of the edge's source arrow.
source_arrow_shape The shape of the edge's source arrow; may be tee, triangle, triangle-tee, triangle-backcurve, square, circle, diamond, or none.
source_arrow_fill The fill state of the edge's source arrow; may be filled or hollow.
mid_source_arrow_color The color of the edge's mid source arrow.
mid_source_arrow_shape The shape of the edge's mid source arrow; may be tee, triangle, triangle-tee, triangle-backcurve, square, circle, diamond, or none.
mid_source_arrow_fill The fill state of the edge's mid source arrow; may be filled or hollow.
target_arrow_color The color of the edge's target arrow.
target_arrow_shape The shape of the edge's target arrow; may be tee, triangle, triangle-tee, triangle-backcurve, square, circle, diamond, or none.
target_arrow_fill The fill state of the edge's target arrow; may be filled or hollow.
mid_target_arrow_color The color of the edge's target arrow.
mid_target_arrow_shape The shape of the edge's target arrow; may be tee, triangle, triangle-tee, triangle-backcurve, square, circle, diamond, or none.
mid_target_arrow_fill The fill state of the edge's target arrow; may be filled or hollow.

Metadata

Contains information information about the graph. Supports the following properties:

Name Description
name Name that is displayed on top of graph while viewing it.
description May be HTML formatted string. May be link to image hosted elsewhere. May simly be a string which contains information such as a legend or significance of the graph.
tags Array of strings. Used to categorize graphs. See Tags for more information.

Example JSON

The following example is a correctly structured JSON for GraphSpace.

{
    "graph": {
        "nodes": [
            {
                "data": {
                    "shape": "ellipse",
                    "id":"P4314611",
                    "content": "DCC",
                    "height": 50,
                    "width": 50,
                    "background_color": "yellow",
                    "background_blacken": 0.1,
                    "border_width": 2,
                    "k": 0
                }
            }, 
            {
                "data": {
                    "shape": "ellipse",
                    "id":"P0810711",
                    "content": "This is an example\n of how to use new lines for the content of\n a node.",
                    "height": 150,
                    "width": 150,
                    "background_color": "red",
                    "background_blacken": 0,
                    "border_width": 5,
                    "border_style": "double",
                    "border_color": "black",
                    "text_wrap": "wrap",
                    "color": "black",
                    "text_outline_width": 2,
                    "text_outline_color": "#888",
                    "k": 0
                }
            }
        ],
        "edges": [
            {
                "data": {
                    "source": "P4314611",
                    "target": "P0810711",
                    "width": 12,
                    "line_color": "blue",
                    "line_style": "dotted",
                    "source_arrow_color": "yellow",
                    "target_arrow_shape": "triangle",
                    "k": 0
                }
            }
        ]

    },
    "metadata": {
        "title": "Graph Name",
        "description": "Description of graph.. can also point to an image hosted elsewhere",
        "tags": [
            "tutorial"
        ]
    }
}

Add graph

In order to add a graph to GraphSpace, make the following POST request where [email] is your email and [password] is your password.
curl -X POST "http://graphspace.org/api/users/[email]/graph/add/[graphname]/" -F "username=[email]" -F "password=[password]" -F graphname=@"path_to_json"; echo
Here is an example of a basic graph JSON:
{
    "graph": {
        "nodes": [
            {
                "data": {
                    "shape": "ellipse",
                    "id":"P4314611",
                    "content": "DCC",
                    "height": 50,
                    "width": 50,
                    "background_color": "yellow",
                    "background_blacken": 0.1,
                    "border_width": 2
                }
            }, 
            {
                "data": {
                    "shape": "ellipse",
                    "id":"P0810711",
                    "content": "This is an example\n of how to use new lines for the content of\n a node.",
                    "height": 150,
                    "width": 150,
                    "background_color": "red",
                    "background_blacken": 0,
                    "border_width": 5,
                    "border_style": "double",
                    "border_color": "black",
                    "text_wrap": "wrap",
                    "color": "black",
                    "text_outline_width": 2,
                    "text_outline_color": "#888"
                }
            }
        ],
        "edges": [
            {
                "data": {
                    "source": "P4314611",
                    "target": "P0810711",
                    "width": 12,
                    "line_color": "blue",
                    "line_style": "dotted",
                    "source_arrow_color": "yellow",
                    "target_arrow_shape": "triangle"
                }
            }
        ]

    },
    "metadata": {
        "title": "Graph Name",
        "description": "Description of graph.. can also point to an image hosted elsewhere",
        "tags": [
            "tutorial"
        ]
    }
}
Example successful response:
{
    "Message": "Graph inserted into GraphSpace!",
    "StatusCode": 201
}
If JSON fails validation, it should give some sort of error as to why it failed
{
    "Error": "Property content not in JSON for node",
    "StatusCode": 400
}

Graph Exists

Checks to see if there is a graph that a user owns in GraphSpace. Note: This command only checks for graphs owned by the user making the request.
curl -X POST "http://graphspace.org/api/users/[email]/graph/exists/[graphname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "User [email] owns a graph with id [graphname]!",
    "StatusCode": 200
}
Example failed response:
{
    "Error": "User [email] owns no graph with id [graphname]!",
    "StatusCode": 404
}

Get graph

To get the JSON for an existing graph use the following GET command. You can only get the JSON for a graph that belongs to you or is shared with a group you belong to. Here, [email] refers to the owner of the graph whose JSON you are trying to retrieve. It may or may not be your email.
curl -X POST "http://graphspace.org/api/users/[email]/graph/get/[graphname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "graph": {
        "nodes": [
            {
                "data": {
                    "shape": "ellipse",
                    "id":"P4314611",
                    "content": "DCC",
                    "height": 50,
                    "width": 50,
                    "background_color": "yellow",
                    "background_blacken": 0.1,
                    "border_width": 2,
                    "k": 0
                }
            }, 
            {
                "data": {
                    "shape": "ellipse",
                    "id":"P0810711",
                    "content": "This is an example\n of how to use new lines for the content of\n a node.",
                    "height": 150,
                    "width": 150,
                    "background_color": "red",
                    "background_blacken": 0,
                    "border_width": 5,
                    "border_style": "double",
                    "border_color": "black",
                    "text_wrap": "wrap",
                    "color": "black",
                    "text_outline_width": 2,
                    "text_outline_color": "#888",
                    "k": 0
                }
            }
        ],
        "edges": [
            {
                "data": {
                    "source": "P4314611",
                    "target": "P0810711",
                    "width": 12,
                    "line_color": "blue",
                    "line_style": "dotted",
                    "source_arrow_color": "yellow",
                    "target_arrow_shape": "triangle",
                    "k": 0
                }
            }
        ]

    },
    "metadata": {
        "title": "Graph Name",
        "description": "Description of graph.. can also point to an image hosted elsewhere",
        "tags": [
            "tutorial"
        ]
    }
}
Example failed response:
{
    "Error": "No Such Graph Exists!",
    "StatusCode": 404
}

Update graph

If a user wants to update any information for a specific graph, they can do so using this command. The user uploads the modified JSON of the graph to the server. Note, a user can only update a graph if it already exists in GraphSpace for that user.
curl -X POST "http://graphspace.org/api/users/[email]/graph/update/[graphname]/" -F "username=[email]" -F "password=[password]" -F graphname=@"path_to_json"
Example successful response:
{
    "Message": "Updated [graphname] for [email].",
    "StatusCode": 201
}
Example failed response:
{
    "Error": "Can't update [graphname] because it does not exist for [email]",
    "StatusCode": 404
}

Remove graph

To remove a graph use the following command. You can only remove a graph that belongs to you.
curl -X POST "http://graphspace.org/api/users/[email]/graph/delete/[graphname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Successfully deleted [graphname] owned by [email].",
    "StatusCode": 200
}
Example failed response:
{
    "Error": "No Such Graph Exists.",
    "StatusCode": 404
}

Get user graphs

Get all ids of graphs belonging to the user making this request. The result is a JSON object containing a list of all graph ids for the specified user.
curl -X POST "http://graphspace.org/api/users/[email]/graphs/" -F "username=[email]" -F "password=[password]"; echo
Example response:
{
    "Graphs": [
        "tutorial_graph1",
        "tutorail_graph2"
    ],
    "StatusCode": 200
}

Get all graphs

Get a summary of all graphs belonging to the user making this request and public graphs (viewable to all users of GS). The result is a JSON object containing a list of summarized inforation about graphs.
curl -X POST "http://graphspace.org/api/graphs/get/" -F "username=[email]" -F "password=[password]" -F "offset=[offset]" -F "limit=[limit]"; echo
Note:
  • Offset is a optional field. Defaults to 10, limits the number of results in the response. Maximum is 1000
  • Limit is a optional field. Defaults to 0, used to offset the resultlist.
Example response:
{
  "metadata": {
    "count": 2,
    "limit": "25",
    "offset": "0"
  },
  "result": [
    {
      "created_at": "2012-10-25T06:29:26",
      "owner_email": "[email]",
      "updated_at": "2013-10-16T17:49:51",
      "num_edges": 2,
      "num_nodes": 1,
      "graphname": "tutorial_graph1"
    },
    {
      "created_at": "2012-10-25T07:03:10",
      "owner_email": "[email]",
      "updated_at": "2013-10-16T17:50:13",
      "num_edges": 2,
      "num_nodes": 1,
      "graphname": "tutorial_graph2"
    }
  "StatusCode": 200
}

Make graph public

Makes a specific graph that user owns public (viewable to all users of GS). All layouts shared with groups will also become public.
curl -X POST "http://graphspace.org/api/users/[email]/graph/makeGraphPublic/[graphname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Successfully made [graphname] owned by [email] public.",
    "StatusCode": 200
}
Example failed response:
{
    "Error": "Graph with name [graphname] doesn't exist under [email].",
    "StatusCode": 404
}

Make graph private

Makes a specific graph that user owns private (only groups that graph is shared with and owner of graph can see it).
curl -X POST "http://graphspace.org/api/users/[email]/graph/makeGraphPrivate/[graphname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Successfully made [graphname] owned by [email] public.",
    "StatusCode": 200
}
Example failed response:
{
    "Error": "Graph with name [graphname] doesn't exist under [email].",
    "StatusCode": 404
}

Groups

Note: All spaces that are contained within the name of a group will be truncated for GET requests. For example, if there is a group named: "Test 1", then the [group_id] for this group would be "Test1".

Create group

To create a group, use the following command. You will be the owner of the group, and you will have to set the description later.
curl -X POST "http://graphspace.org/api/groups/add/[group_owner]/[groupname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Group Id": "Test2",
    "Message": "Group created!",
    "Group Name": "Test2",
    "StatusCode": 201
}
Example failure response:
{
    "Error": "Group name already exists for this account",
    "StatusCode": 400
}

Remove group

To remove a group use the following command. You can only remove a group that you are the owner of.
curl -X POST "http://graphspace.org/api/groups/delete/[group_owner]/[groupname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Successfully deleted [groupname] owned by [group_owner].",
    "StatusCode": 200
}

Example failed response:
{
    "Message": "Group not found!",
    "StatusCode": 200
}

Get group

Get a group by id. The result is a JSON object with the group's id, description, and owner, as well as the list of users belonging to the group, and the list of graph ids (and the user ids for those graphs) that are shared with the group.
curl -X POST "http://graphspace.org/api/groups/get/[group_owner]/[group_id]/" -F "username=[email]" -F "password=[password]"; echo
{
    "Groups": {
        "owner": "dsingh5270@gmail.com",
        "graphs": [
            "api_test",
            "secret_feature"
        ],
        "group_id": "Test1",
        "description": "This is test group to see if changing description works properly.",
        "members": [
            "annaritz@vt.edu",
            "ategge@vt.edu",
            "dsingh5270@gmail.com"
        ]
    },
    "StatusCode": 200
}

Get groups a user belongs to

Get groups a user belongs to. The result is a JSON object with a list of group ids.
curl -X POST "http://graphspace.org/api/users/[email]/groups/" -F "username=[email]" -F "password=[password]"; echo
Example response:
{
  "Groups": [
      {
          "group_owner": "[email]",
          "groupId": "[Test1]"
      }
  ],
  "StatusCode": 200
}

Add user to group

Add a user to a group. You can only add a user to a group that you belong to.
curl -X POST "http://graphspace.org/api/groups/[group_owner]/[groupname]/adduser/[member]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Successfully added user [member] to [groupname].",
    "StatusCode": 200
}
Example failed response:
{
    "Error": "Group doesn't exist or user has already been added!",
    "StatusCode": 400
}

Remove user from group

Remove a user from a group. You can remove yourself from any group, but you must be the owner of a group to remove other members.
curl -X POST "http://graphspace.org/api/groups/[group_owner]/[groupname]/removeuser/[member]/" -F "username=[email]" -F "password=[email]"; echo
Example successful response:
{
    "Message": "Successfully removed user [member] from [groupname].",
    "StatusCode": 200
}

Share graph with a group

Share a graph with a group, effectively giving all members in the group the ability to see a graph. You can only share graphs you own with groups you are a member of or the owner of.
curl -X POST "http://graphspace.org/api/users/graphs/[graph name]/share/[group_owner]/[group name]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Graph successfully shared with group!",
    "StatusCode": 200
}

Unshare graph with a group

Unshare a graph with a group, effectively removing read permission from all members in the group. You can only unshare graphs you own from groups you belong to.
curl -X POST "http://graphspace.org/api/users/graphs/[graphname]/unshare/[group_owner]/[group name]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Graph successfully unshared with group!",
    "StatusCode": 200
}

Layouts

Get all layouts for a Graph

Get all the layouts that are attached to a certain graph.
curl -X POST "http://graphspace.org/api/users/[email]/graph/[graphname]/layouts/get" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "metadata": {
        "count": 2,
        "limit": 10,
        "offset": 0
    },
    "result": [
        {
            "graph_id": "tutorial_graph1",
            "layout_id": 3,
            "json": "{}",
            "user_id": "[email]",
            "layout_name": "test_layout1",
            "owner_id": "[email]"
        },
        {
            "graph_id": "tutorial_graph2",
            "layout_id": 607,
            "json": "{}",
            "user_id": "[email]",
            "layout_name": "test_layout2",
            "owner_id": "[email]"
        }
    ],
    "StatusCode": 200
}

Get layout

To get the JSON for an existing layout use the following command. You can only get the JSON for a layout that belongs to you or is shared with a group you belong to or available for public access. Here, [layout_id] refers to id of the layout whose JSON you are trying to retrieve.
curl -X POST "http://graphspace.org/layouts/get/[layout_id]" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
  "graph_id": "[graph_id]",
  "layout_id": [layout_id],
  "json": "[layout_json]",
  "user_id": "[graph_owner]",
  "layout_name": "[layout_name]",
  "owner_id": "[layout_owner]"
}

Create layout

In order to add a layout to a graph, make the following POST request where [email] is your email, [password] is your password, [layout_name] is the name of layout and [json] is the layout data as a JSON string.
curl -X POST "http://graphspace.org/api/users/[email]/graph/[graphname]/layouts/add" -F "username=[email]" -F "password=[password]" -F "json=[json]" -F "layout_name=[layout_name]"; echo
Example successful response:
{
  "Message": "Added [layout_name] layout with id=619.",
  "StatusCode": 201
}

Update layout

If a user wants to update any information for a specific layout, they can do so using this command. The user uploads the modified JSON of the layout to the server. Note, a user can only update a layout if it already exists in GraphSpace for that user.
curl -X POST "http://graphspace.org/layouts/update/[layout_id]" -F "username=[email]" -F "password=[password]" -F "json=[json]"; echo
Example successful response:
{
  "Message": "Updated Layout with id=[layout_id].",
  "StatusCode": 201
}
Example failed response:
{
  "Error": "No Such Layout Exists!",
  "StatusCode": 404
}

Tags

Get Tags for User

Get all the tags that a user has for their graphs.
curl -X POST "http://graphspace.org/api/tags/user/[email]/" -F "username=[email]" -F "password=[password]"
Example successful response:
{
    "Tags": [
        "tutorial,
        "pathways",
        "pictures",
    ],
    "StatusCode": 200
}

Get Tags for a Graph

Get all the tags that are attached to a certain graph.
curl -X POST "http://graphspace.org/api/tags/user/[email]/[graphname]/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Tags": [
        "tutorial"
    ],
    "StatusCode": 200
}

Make all graphs for a tag public

Changes the privacy of all graphs that contain a [tag] under [email] public.
curl -X POST "http://graphspace.org/api/tags/user/[email]/[tag]/makePublic/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Graphs with tag have been made public",
    "StatusCode": 200
}

Make all graphs for a tag private

Changes the privacy of all graphs that contain a [tag] under [email] private.
curl -X POST "http://graphspace.org/api/tags/user/[email]/[tag]/makePrivate/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Graph with tag have been made private",
    "StatusCode": 200
}

Delete all graphs for a tag

Delets all graphs that contain a [tag] under [email].
curl -X POST "http://graphspace.org/api/tags/user/[email]/[tag]/delete/" -F "username=[email]" -F "password=[password]"; echo
Example successful response:
{
    "Message": "Graphs with tag have been deleted",
    "StatusCode": 200
}