PTGLweb REST API

The PTGLweb Application Programming Interface (API) allows you to quickly retrieve data from the PTGLweb programmatically. This page explains how to use the API.

A typical use case is that you want more data than you are willing to download manually by clicking in your web browser. You may, for example, have a list of 250 PDB chains, and you want the albe protein graphs for all of them in GML format.

If you are not a programmer, you may prefer the HTML interface of the PTGLweb.

Data available via the API

You can retrieve protein graph (PG) and folding graph (FG) data in GML and JSON formats. You can also retrieve the linear notations (linnots) of a folding graph as a string. It is also possible to retrieve the graph images -- both the PG visualization and the 4 different linnot visualizations.

The PTGLweb is a protein topology database which works mainly on the level of a protein chain: a protein graph includes all the secondary structure elements (SSEs) of a chain. (Which SSEs types are included is determined by the graph type, e.g., the alpha graph only contains alpha helices, while the alpha-beta graph contains both alpha helices and beta strands.)

You may have guessed it, but all methods provided are GET. You cannot alter (insert, update, delete) any data on the server using this API.

Addressing data

All data must be retrieved via GET. Atm, no authentication is required to access the API.

Learn howto address: Protein graphs | Folding graphs | Linear notations | Motifs

Addressing Protein graphs and their visualization

The data is addressed by the following information for a Protein graph:

/pg/<pdbid>/<chain>/<graphtype>/<graphformat>

<pdbid> an RCSB PDB identifier for a protein (4 letter RCSB PDB protein code, e.g., 7tim.)
<chain> a PDB chain name (1 letter RCSB PDB chain name, e.g., A). See the metadata section to learn how to find all valid chain names for a certain protein.
<graphtype> a graph type (PTGLweb graph type name. The following 6 values are valid: alpha, beta, albe, alphalig, betalig, albelig)
<graphformat> a graph file format (The following 3 values are valid: gml, json, xml. For more information on these formats, search the web for Graph Modelling Language (gml), JavaScript Object Notation (json), or Extensible Markup Language (XML). For the XML, we are not using some home-brew XML, but the the eXtensible Graph Markup and Modeling Language (XGMML).)

You can also get the visualization of a protein graph as an image:

/pgvis/<pdbid>/<chain>/<graphtype>/<imageformat>

You need all the info from the PG except for the <graphformat>, plus the following extra information:

<imageformat> an image file format (The following 2 values are valid: png, svg)

Addressing Folding graphs and their visualization

A Folding graph (FG) is a single connected component of a protein graph (PG). To address a folding graph, you need: Folding graph query format:

/fg/<pdbid>/<chain>/<graphtype>/<fold>/<graphformat>

all the data for a protein graph (see above) and
<fold> the fold number, an integer equal to or greater than zero. See the metadata section to learn how to find all valid chain names for a certain protein.

You can also get the visualization of a folding graph as an image. This will return the new DEF folding graph visualization, which shows the folding graph within the parent protein graph: the vertices and edges of the FG are colored, while the other (PG-only) vertices and edges are drawn in gray. See addressing Linear notations below if you want the ADJ, RED, SEQ or KEY notation visualization of the FG instead.

/fgvis/<pdbid>/<chain>/<graphtype>/<fold>/<imageformat>

You need all the info from the FG except for the <graphformat>, plus the following extra information:

<imageformat> an image file format (The following 2 values are valid: png, svg)

Addressing Linear notations and their visualizations

There exist 4 different linear notation strings to describe the same folding graph. Each of them has a diffenerent visualization. To address a linear notation, you need:

/linnot/<pdbid>/<chain>/<graphtype>/<fold>/<linnot>

all the data for a folding graph (see above) and
<linnot> the linear notation name (The following 4 values are valid: adj, red, seq, key)

You can also get the visualization of a linear notation as an image:

/linnotvis/<pdbid>/<chain>/<graphtype>/<fold>/<linnot>/<imageformat>

You need all the info from the linnot, plus the following extra information:

<imageformat> an image file format (The following 2 values are valid: png, svg)

Note that the KEY notation is not defined for bifurcated graphs and may thus return the empty string for a fold.

Usage examples

Here are some example queries against the API:

Protein graphs:

/api/index.php/pg/7tim/A/albe/json retrieves the albe (alpha-beta) graph of PDB 7TIM, chain A in JSON format.
/api/index.php/pg/7tim/A/albe/gml retrieves the same protein graph in Graph Modelling Language (GML) format.
/api/index.php/pg/7tim/A/albe/xml retrieves the same protein graph in XGMML, an XML-based graph format based on GML.
/api/index.php/pgvis/7tim/A/albe/png retrieves the same protein graph's visualization in PNG format.

Folding graphs:

/api/index.php/fg/7tim/A/albe/0/json retrieves the folding graph #0 of the alpha-beta graph of PDB 7TIM, chain A in JSON format.
/api/index.php/fg/7tim/A/albe/0/gml retrieves the same folding graph in GML format.
/api/index.php/fg/7tim/A/albe/0/xml retrieves the same folding graph in XGMML (XML) format.
/api/index.php/fgvis/7tim/A/albe/0/png retrieves the same folding graph's DEF visualization in PNG format.

Linear notations:

api/index.php/linnot/7tim/A/albe/0/adj/json retrieves the ADJ linear notation of folding graph #0 of the alpha-beta graph of PDB 7TIM, chain A. This is a string in JSON format.
api/index.php/linnotvis/7tim/A/albe/0/adj/png retrieves the visualization of the ADJ linear notation of folding graph #0 of the alpha-beta graph of PDB 7TIM, chain A. This is an image in PNG format.

Metadata queries

To automatically process all data of a certain type, it is very handy to know which data is available. For example, you may want to process all chains of a protein -- but how do you know the chain names? The same applies to the number of connected components (folding graphs) of a protein graph -- how do you know how many connected components a protein graph has? We also provide methods to get this information:

All chain names of a protein:

format: /chains/<pdbid>
example: /api/index.php/chains/7tim/ retrieves all available chain names of all chains of 7tim. This is a list of strings, the format is always JSON. Output would be ["A", "B"] for this example.

All folding graph numbers of a protein graph:

format: /folds/<pdbid>/<chain>/<graphtype>
example: /api/index.php/folds/7tim/A/albe retrieves all available fold numbers of the albe graph of 7tim chain A. This is a list of integers, the format is always JSON. Output would be [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] for this example.

Motif queries

To query for PDB chains containing a motif, you need the following information:

<motifname> the name of the motif.

Note that this returns a very long list for some motifs. The following names (in bold) are available:

4helix : 4 helix bundle
globin : globin fold
barrel : beta barrel
immuno : immunoglobin fold
propeller : beta propeller
jelly : jelly roll
ubi : ubiquitin fold
plait : beta plait
rossman : rossman fold
tim : TIM barrel

All of these return data in JSON format only:

A JSON list of all protein chains (e.g., '7timA') that contain a certain motif:

format: /pdbchains_containing_motif/<motifname>/json
example: /api/index.php/pdbchains_containing_motif/4helix/json retrieves a list of protein chains that contain the 4helix motif in JSON format.

Example code to access this API

PHP

Here is some simple example code which queries this API from PHP, using libcurl. The code retrieves the ADJ linear notation string of the albe graph of 7tim chain A. Feel free to use and extend it.

<?php
$url_linnot = 'http://ptgl.uni-frankfurt.de/api/index.php/linnot/7tim/A/albe/0/adj';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url_linnot);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FAILONERROR, 1);

$result = curl_exec($curl);

if(curl_errno($curl)) {
    // TODO: handle error here
    echo 'ERROR: ' . curl_error($curl);
}
else {
    // TODO: do something with the result here
    // the result will be "{h,3ph,-2me,-3pe,-2pe,-2pe,-2pe,18pe,-2pe,-4pe,-3pe,2zh,3ph,2me}"
    echo "OK. adj string: " . json_decode($result);    
}
?>

BASH shell

We also provide a BASH shell script for Linux that will download the GML files for a list of proteins or chains. The list can be in a CSV file. The script and an example list is available for download here: bash_api_example.zip. The script comes without any warranty. Make sure you understand it and adapt it to your needs before usage. The script uses wget, awk, tr and other standard unix tools.

Welcome to the PTGLweb API

Basics