API for STRING 8.0 still accessible

After the release of STRING 8.1, the previous version, 8.0, can still be accessed: http://string80.embl.de. Under this URL, the API continues to work, e.g.:

http://string80.embl.de/api/tsv/interactors?identifier=DRD1_HUMAN

This pattern will continue for upcoming releases (you could also use "string81" as host name now to stay on this version even if we update to a new version).

100 API accesses per minute: not a good idea

STRING was unreachable for some time this morning while it was busy processing ~10,000 API requests in about 1.5 hours. 100 API accesses per minute is not a good idea, as this overloads our server, making STRING (and STITCH) unavailable for everyone. Don't run scripts that access the API in parallel.

If you want to do large-scale analysis on STRING data, you can make your and our life much easier by signing an academic license agreement and downloading the full dataset.

API also available on STRING

When I created the API, I only put it on STITCH. Of course there's no reason to not have it also on STRING, so here you go:

http://string.embl.de/api/tsv/interactors?identifier=DRD1_HUMAN

It's in the same state as the STITCH API: Still subject to change, and potentially unstable.

Getting identifiers for a list of genes

If you want to to quickly get identifiers for a long list of items you can use the following command, which uses wget to repeatedly query the API.

cat protein_names.txt | xargs -i wget -nv -O - \
'http://stitch.embl.de/api/tsv-no-header/resolve?identifier={}&species=4932&echo_query=1' \
> protein_identifiers.tsv

I've also introduced another parameter, echo_query, so that you can see your query item in the output.

Embedding protein/chemical information into other web pages

One of the nice things about STRING/STITCH is that you can click on any item and be presented with a helpful pop-up describing the item in question. :-)

As you can see, for a protein, we show links to different servers, the domain structure and if possible a representative PDB structure. For a chemical we currently only show the structure and link to PubChem.

In order to use the same pop-up in Reflect (a cool tool that recognizes and annotates proteins and chemical any web page), we made a service out of it. The functionality is going to change in the future, but here are two working examples:

http://stitch.embl.de/services/iteminfo?node=9606.ENSP00000186982
http://stitch.embl.de/services/iteminfo?node=CID2244
The idea is that you can take this raw HTML and put it into an iframe with JavaScript. (This is left as an exercise to the reader... future versions of STRING may use this technique to make the pages a bit smaller.) For now, it only accepts internal STRING identifiers, which you either get from our download files or from the API.

Scope of the API and current plans

When I announced the API, I didn't devote much space to the intended scope of the API. To make things clearer:

• REST/SOAP: We'll only provide a REST API plus a Soaplab2 wrapper for Taverna. Perhaps later dedicated programmers can add a SOAP interface if the demand is sufficiently high.
• Queries for bulk data: For implementation and licensing reasons, we'll only provide methods to query by individual items, just like on the web site. If you need access to bulk data, you can download it.
• Miscellaneous records: We want to add more query options later for retrieving information from the freely available files. For example: What are the synonyms of this item? To which orthologous group does this protein belong?
  

Example Taverna workflow

Taverna is a tool that lets you connect web services from different sources with each other. I've implemented a simple example workflow (.xml): You enter a human protein or chemical of interest, STITCH will identify the matching item(s), generate an interaction network and retrieve the 10 most relevant abstracts. The list of Pubmed ids is then passed on to Whatizit, which highlights disease terms in the abstracts. A simple Python script then counts the diseases.

Try it out; try other things; tell me what you think.
Note: The Python script is called via the Soaplab interface. I tried to do this in Taverna but gave up, it didn't like my XPath (due to the XML produced by Whatizit) and writing a Beanshell script seemed more cumbersome.

We have an API!

I went to the BioHackathon 2008 in Tokyo and worked on an API for STRING and STITCH. If you think about using STRING or STITCH with an API, and miss features, please get in touch with us either via the comments or e-mail (e.g. mkuhn//embl.de).

Here's what we have to offer so far:

REST interface

The URL patterns are: http://stitch.embl.de/api/[format]/[request]?[parameters]
http://string.embl.de/api/[format]/[request]?[parameters]

Possible formats:

• tsv: tab-separated values, with a header line
  
• tsv-no-header: as above, but no header
• json: JSON format either as a list of hashes/dictionaries, or as a plain list (if there is only one value to be returned per record)
• psi-mi: the interaction network is available in PSI-MI 2.5 XML format
• psi-mi-tab: there is also a tab-delimited form, modeled after the IntAct specification. This is easier to parse, but contains less information than the XML format.
• url: return the URL of the network image
  

Possible requests:

• abstracts: return a list of abstracts that contain the query item
  
• abstractsList: return a list of abstracts that contain any of the query items
• interactions: return an interaction network in PSI-MI 2.5 format (PSI-MI is currently the only format for interactions. Perhaps the PSI-MI tab-delimited form would also make sense? I don't know how a JSON form should look like.)
• interactionsList: same as above, but for list of identifiers
  
• interactors: return a list of interaction partners for the query item
• interactorsList: return a list of interaction partners for any of the query item
• resolve: return the list of items that match (in name or identifier) the query item
• network / networkList: in conjunction with the "url" format, return the URL to the network
  

For a full list of possible parameters, please refer to our STRING Soaplab 2 interface. With the help of Soaplab2 / Gowlab, we'll describe the set of possible parameters there. (Doesn't work right now. :-/ )

Examples

To find out which proteins match the description "dopamine receptor" in human, you can use this query:

http://stitch.embl.de/api/tsv/resolve?identifier=dopamine%20receptor&species=9606
http://string.embl.de/api/tsv/resolve?identifier=dopamine%20receptor&species=9606

This gives you a lot of additional info. If you just want to get the list of STRING identifiers, you can alter the query a bit:

http://stitch.embl.de/api/tsv-no-header/resolve?identifier=dopamine%20receptor&species=9606&format=only-ids
http://string.embl.de/api/tsv-no-header/resolve?identifier=dopamine%20receptor&species=9606&format=only-ids

Now, you'll only receive a bare list of ids that you could pipe into other STRING API functions.

To illustrate the difference between normal and "list" queries:

http://stitch.embl.de/api/tsv/interactors?identifier=DRD1_HUMAN
http://stitch.embl.de/api/tsv/interactorsList?identifiers=DRD1_HUMAN%0DDRD2_HUMAN

http://string.embl.de/api/tsv/interactors?identifier=DRD1_HUMAN
http://string.embl.de/api/tsv/interactorsList?identifiers=DRD1_HUMAN%0DDRD2_HUMAN


In the second case, the identifiers parameter contains a list of items separated by new line characters (%0A or %0D).

SOAP / Taverna

In a separate post, I've described an example Taverna workflow. As for SOAP integration, I hope that the Soaplab interface works...

Obligatory beta notice

As all good things these days, this is still in beta (internally, everything in fact runs on our beta server, I'm just making it accessible via the normal STITCH domain to expose it to the web). Therefore, the API might change, be down, ... until STITCH 2 / STRING 8 comes out.

Updates

03.03.2008: Added clarification – PSI-MI is currently the only interactions format.
04.03.2008: Fixed typo – it's "interactorsList"
12.03.2008: Add psi-mi-tab format
19.05.2008: Add STRING API (with same specification)
08.07.2008: Add API for generating network images
16.03.2009: Enabled interactionsList