BioGRID REST Service
Differences
This shows you the differences between two versions of the page.
|
biogridrest [2012/03/01 14:12] biogridadmin [List of Parameters] |
biogridrest [2013/06/02 23:56] (current) biogridadmin [Examples] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== BioGRID REST Service ====== | ====== BioGRID REST Service ====== | ||
| - | Interaction data in BioGRID can be accessed via the BioGRID REST service. Interactions in various formats can be fetched from the BioGRID REST Service over HTTP, programmatically or in a browser, at | + | Interaction data in BioGRID can be accessed via the BioGRID REST service. Interactions in various formats can be fetched from the BioGRID REST Service over HTTP, programmatically or in a browser, at |
| - | http://webservice.thebiogrid.org/resources/interactions/ | + | **http://webservice.thebiogrid.org/interactions/**. You can access interactions using both POST and GET operations depending on your application requirements. |
| - | This URL will retrieve the first 10,000 interactions in BioGRID, ordered by the BioGRID Interaction Id as found in .tab2 files. Single interactions can be retrieved by appending this URL with a Biogrid Interaction ID (e.g. http://webservice.thebiogrid.org/resources/interactions/103). The results list returned can be filtered by appending ?parameter1=value1& parameter2=value2 etc. to the URL. A full description of possible parameters is given in the table below. | + | |
| - | A formal description of the REST service, in Web Application Description Language (WADL), can be found at http://webservice.thebiogrid.org/resources/application.wadl. The BioGRID REST service is updated to the latest release of BioGRID on the 2nd of each month and the BioGRID database version being accessed can be determined with the URL: | + | |
| - | http://webservice.thebiogrid.org/resources/version . | + | |
| - | In addition to BioGRID interaction data, interactions from the IMEx databases have been included (see [[imex_import|Import of IMEx interactions into BioGRID REST Service]]) as an option for retrieval in the REST service data. The URL parameter “sourceDatabaseList” has a default value of “BioGRID”, but if set to “BioGRID|MINT|INTACT|DIP” the query will retrieve interactions from all databases. Source database origin can be found in the “Source Databases” column of the retrieved data and the “Source Database Identifiers” column (if the parameter format=extendedTab2 is set) allows mapping back to the interaction in the original database. IMEx interaction files are downloaded from their respective websites and integrated into the REST service to coinicide with each monthly BioGRID release. These additional interactions are only available through the BioGRid REST Service and are not currently present in the BioGRID download files. | + | ==== Get Your Access Key ==== |
| + | To access the BioGRID REST webservice, you will need a unique access key for your application. You can get one by filling out the simple form located **[[http://webservice.thebiogrid.org|here]]**. This key must be included in all queries to the webservice in the form of accesskey=[ACCESSKEY]. | ||
| + | |||
| + | ==== Fetching Single Interactions ==== | ||
| + | The URL **http://webservice.thebiogrid.org/interactions/?accesskey=[ACCESSKEY]** will retrieve the first 10,000 interactions in BioGRID, ordered by the BioGRID Interaction Id as found in **[[biogrid_tab_version_2.0|.tab2]]** files. Single interactions can be retrieved by appending this URL with a Biogrid Interaction ID (e.g. **http://webservice.thebiogrid.org/interactions/103?accesskey=[ACCESSKEY]**). | ||
| + | |||
| + | ==== Filtering Results ==== | ||
| + | The results list returned can be filtered by appending ?parameter1=value1¶meter2=value2 etc. to the URL. A full description of possible parameters is given in the **[[#list_of_parameters|table below]]**. | ||
| + | |||
| + | A formal description of the REST service, in Web Application Description Language (WADL), can be found at **http://webservice.thebiogrid.org/application.wadl**. | ||
| + | |||
| + | ==== Updates and Version ==== | ||
| + | The BioGRID REST service is updated to the latest release of BioGRID on the 2nd of each month and the BioGRID database version being accessed can be determined with the URL: | ||
| + | **http://webservice.thebiogrid.org/version?accesskey=[ACCESSKEY]**. | ||
| ===== Examples ===== | ===== Examples ===== | ||
| Line 12: | Line 22: | ||
| === Interactions for human MDM2 gene: === | === Interactions for human MDM2 gene: === | ||
| - | http://webservice.thebiogrid.org/resources/interactions?searchNames=true&geneList=MDM2&includeInteractors=true&includeInteractorInteractions=false&taxId=9606 | + | **http://webservice.thebiogrid.org/interactions?searchNames=true&geneList=MDM2&includeInteractors=true&includeInteractorInteractions=false&taxId=9606&accesskey=[ACCESSKEY]** |
| === Interactions for human MDM2 gene and interactions between all interactors of MDM2: === | === Interactions for human MDM2 gene and interactions between all interactors of MDM2: === | ||
| - | http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=MDM2&taxId=9606&includeInteractors=true&includeInteractorInteractions=true | + | **http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=MDM2&taxId=9606&includeInteractors=true&includeInteractorInteractions=true&accesskey=[ACCESSKEY]** |
| === First 10 interactions for human MDM2 gene: === | === First 10 interactions for human MDM2 gene: === | ||
| - | http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=MDM2&includeInteractors=true&includeInteractorInteractions=false&taxId=9606&start=0&max=10 | + | **http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=MDM2&includeInteractors=true&taxId=9606&start=0&max=10&accesskey=[ACCESSKEY]** |
| === Interactions between S. cerevisiae CDC27, APC1 and APC2: === | === Interactions between S. cerevisiae CDC27, APC1 and APC2: === | ||
| - | [[http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=cdc27%7Capc1%7Capc2&taxId=4932|http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=cdc27|apc1|apc2&taxId=4932]] | + | **[[http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=cdc27%7Capc1%7Capc2&taxId=559292&accesskey=[ACCESSKEY]|http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=cdc27|apc1|apc2&taxId=559292&accesskey=[ACCESSKEY]]]** |
| === Interactions from pubmed IDs 18316726 and 17662948: === | === Interactions from pubmed IDs 18316726 and 17662948: === | ||
| - | [[http://webservice.thebiogrid.org/resources/interactions/?pubmedList=18316726%7C17662948|http://webservice.thebiogrid.org/resources/interactions/?pubmedList=18316726|17662948]] | + | **[[http://webservice.thebiogrid.org/interactions/?pubmedList=18316726%7C17662948&accesskey=[ACCESSKEY]|http://webservice.thebiogrid.org/interactions/?pubmedList=18316726|17662948&accesskey=[ACCESSKEY]]]** |
| === Interactions between CDC27, APC1 and APC2 from publications with 50 or less interactions: === | === Interactions between CDC27, APC1 and APC2 from publications with 50 or less interactions: === | ||
| - | [[http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=cdc27%7Capc1%7Capc2&htpThreshold=50&excludePubmeds=true|http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=cdc27|apc1|apc2&htpThreshold=50&excludePubmeds=true]] | + | **[[http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=cdc27%7Capc1%7Capc2&htpThreshold=50&excludePubmeds=true&accesskey=[ACCESSKEY]|http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=cdc27|apc1|apc2&htpThreshold=50&excludePubmeds=true&accesskey=[ACCESSKEY]]]** |
| === Interactions between CDC27, APC1 and APC2 excluding ‘Affinity Capture-MS’ and ‘Two-hybrid’ data: === | === Interactions between CDC27, APC1 and APC2 excluding ‘Affinity Capture-MS’ and ‘Two-hybrid’ data: === | ||
| - | [[http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=cdc27%7Capc1%7Capc2&evidenceList=Affinity Capture-MS%7CTwo-hybrid|http://webservice.thebiogrid.org/resources/interactions/?searchNames=true&geneList=cdc27|apc1|apc2&evidenceList=Affinity Capture-MS|Two-hybrid]] | + | **[[http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=cdc27%7Capc1%7Capc2&evidenceList=Affinity Capture-MS%7CTwo-hybrid&accesskey=[ACCESSKEY]|http://webservice.thebiogrid.org/interactions/?searchNames=true&geneList=cdc27|apc1|apc2&evidenceList=Affinity Capture-MS|Two-hybrid&accesskey=[ACCESSKEY]]]** |
| - | === Interactions from pubmed ID18316726, excluding those containing HTLF: === | + | === Interactions between genes with GENBANK_DNA_GI 82502895 (TP53) or 158261704 (MDM2), in extendedTab2 format === |
| - | http://webservice.thebiogrid.org/resources/interactions/?pubmedList=18316726&searchNames=true&geneList=HLTF&excludeGenes=true | + | **[[http://webservice.thebiogrid.org/interactions/?additionalIdentifierTypes=GENBANK_DNA_GI&geneList=82502895%7C158261704&format=extendedTab2&accesskey=[ACCESSKEY]|http://webservice.thebiogrid.org/interactions/?additionalIdentifierTypes=GENBANK_DNA_GI&geneList=82502895|158261704&format=extendedTab2&accesskey=[ACCESSKEY]]]** |
| - | + | ||
| - | === Interactions between genes with GENBANK_DNA_GI 82502895 (TP53) or 158261704 (MDM2), in extendedTab2 format with a header: === | + | ====== List of Parameters ====== |
| - | + | ||
| - | [[http://webservice.thebiogrid.org/resources/interactions/?additionalIdentifierTypes=GENBANK_DNA_GI&geneList=82502895%7C158261704&format=extendedTab2&includeHeader=true|http://webservice.thebiogrid.org/resources/interactions/?additionalIdentifierTypes=GENBANK_DNA_GI&geneList=82502895|158261704&format=extendedTab2&includeHeader=true]] | + | |
| - | + | ||
| - | + | ||
| - | ===== List of Parameters ===== | + | |
| ^Parameter^Type^Default^Valid Values^Description^ | ^Parameter^Type^Default^Valid Values^Description^ | ||
| Line 54: | Line 59: | ||
| |interSpeciesExcluded|boolean|FALSE|true, false|If ‘true’, interactions with interactors from different species will be excluded.| | |interSpeciesExcluded|boolean|FALSE|true, false|If ‘true’, interactions with interactors from different species will be excluded.| | ||
| |selfInteractionsExcluded|boolean|FALSE|true, false|If ‘true’, interactions with one interactor will be excluded.| | |selfInteractionsExcluded|boolean|FALSE|true, false|If ‘true’, interactions with one interactor will be excluded.| | ||
| - | |evidenceList|string|empty|Pipe-separated list of evidence codes from http://wiki.thebiogrid.org/doku.php/experimental_systems|Any interaction evidence with its Experimental System in the list will be excluded from the results unless includeEvidence is set to true.| | + | |evidenceList|string|empty|Pipe-separated list of evidence codes from **[[http://wiki.thebiogrid.org/doku.php/experimental_systems|here]]**|Any interaction evidence with its Experimental System in the list will be excluded from the results unless includeEvidence is set to true.| |
| |includeEvidence|boolean|FALSE|true, false|If set to true, any interaction evidence with its Experimental System in the evidenceList will be included in the result| | |includeEvidence|boolean|FALSE|true, false|If set to true, any interaction evidence with its Experimental System in the evidenceList will be included in the result| | ||
| |geneList|string|empty|Pipe-separated list of gene names or identifiers.|Interactions between genes in this list will be fetched. This parameter is ignored if one of searchIds, searchNames, searchSynonyms is not ‘true’ and additionalIdentifierTypes is empty.| | |geneList|string|empty|Pipe-separated list of gene names or identifiers.|Interactions between genes in this list will be fetched. This parameter is ignored if one of searchIds, searchNames, searchSynonyms is not ‘true’ and additionalIdentifierTypes is empty.| | ||
| Line 60: | Line 65: | ||
| |searchNames|boolean|FALSE|true, false|If ‘true’, the interactor OFFICIAL_SYMBOL will be examined for a match with the geneList.| | |searchNames|boolean|FALSE|true, false|If ‘true’, the interactor OFFICIAL_SYMBOL will be examined for a match with the geneList.| | ||
| |searchSynonyms|boolean|FALSE|true, false|If ‘true’, the interactor SYNONYM will be examined for a match with the geneList.| | |searchSynonyms|boolean|FALSE|true, false|If ‘true’, the interactor SYNONYM will be examined for a match with the geneList.| | ||
| - | |additionalIdentifierTypes|string|empty|Pipe-separated list of identifier types from http://wiki.thebiogrid.org/doku.php/identifiers|Identifier types on this list are examined for a match with the geneList.| | + | |additionalIdentifierTypes|string|empty|Pipe-separated list of identifier types from **[[http://wiki.thebiogrid.org/doku.php/identifiers|here]]**|Identifier types on this list are examined for a match with the geneList.| |
| |excludeGenes|boolean|FALSE|true, false|If ‘true’, interactions containing genes in the geneList will be excluded from the results. Ignored if one of searchIds, searchNames, searchSynonyms is not ‘true’ and additionalIdentifierTypes is empty.| | |excludeGenes|boolean|FALSE|true, false|If ‘true’, interactions containing genes in the geneList will be excluded from the results. Ignored if one of searchIds, searchNames, searchSynonyms is not ‘true’ and additionalIdentifierTypes is empty.| | ||
| |includeInteractors|boolean|FALSE|true, false|If ‘true’, in addition to interactions between genes on the geneList, interactions will also be fetched which have only one interactor on the geneList i.e. the geneList’s first order interactors will be included| | |includeInteractors|boolean|FALSE|true, false|If ‘true’, in addition to interactions between genes on the geneList, interactions will also be fetched which have only one interactor on the geneList i.e. the geneList’s first order interactors will be included| | ||
| Line 70: | Line 75: | ||
| |taxId|string|“All”|Any NCBI taxonomy identifier or "All"|Only interactions with at least one interactor with this NCBI taxonomy id will be included in the results.| | |taxId|string|“All”|Any NCBI taxonomy identifier or "All"|Only interactions with at least one interactor with this NCBI taxonomy id will be included in the results.| | ||
| |includeHeader|boolean|FALSE|true, false|If ‘true’, the first line of the result will be a BioGRID column header, appropriate for the format parameter (‘count’ format has no header).| | |includeHeader|boolean|FALSE|true, false|If ‘true’, the first line of the result will be a BioGRID column header, appropriate for the format parameter (‘count’ format has no header).| | ||
| - | |sourceDatabaseList|string|“BioGRID”|Pipe-separated list of database names, currently including BioGRID, INTACT, MINT, DIP|Only interactions with Source Database on this list will be returned.| | ||
| - | |sourceDatabaseIdList|string|empty|Pipe-separated list of source database identifiers|Interactions with a source database interaction ID in the list will be included in the results. The source database for the identifier must also be selected using sourceDatabaseList.| | ||
| |format|string|“tab2”|“tab1”,”tab2,”extendedTab2”,”count”|‘tab1’ and ‘tab2’ will return data in .tab or .tab2 format respectively. ‘extendedTab2’ will return data in .tab2 file format with extra fields fields for "Source Database Identifiers", "Number of Interactions per Publication" and "Additional Identifiers". "Source Database Identifiers" are listed in order corresponding to the values in "Source Databases" e.g if an interaction has %%BIOGRID|INTACT|MINT in Source_Database, it might have 821622|EBI-1792672|MINT-1999291%%| | |format|string|“tab2”|“tab1”,”tab2,”extendedTab2”,”count”|‘tab1’ and ‘tab2’ will return data in .tab or .tab2 format respectively. ‘extendedTab2’ will return data in .tab2 file format with extra fields fields for "Source Database Identifiers", "Number of Interactions per Publication" and "Additional Identifiers". "Source Database Identifiers" are listed in order corresponding to the values in "Source Databases" e.g if an interaction has %%BIOGRID|INTACT|MINT in Source_Database, it might have 821622|EBI-1792672|MINT-1999291%%| | ||
| |enableCaching|boolean|false|true, false|If set to true, a header is added to the HTTP response, 'Cache-Control: max-age=86400', which allows repeat queries performed within a day to use a cached copy of the results, allowing faster access to data. WARNING: The BioGRID REST service updates to the new version at 12pm GMT on the 2nd of each month, meaning that you may receive 'old' data for up to a day for previously performed queries - even if http://webservice.thebiogrid.org/resources/version indicates the new version is being used.| | |enableCaching|boolean|false|true, false|If set to true, a header is added to the HTTP response, 'Cache-Control: max-age=86400', which allows repeat queries performed within a day to use a cached copy of the results, allowing faster access to data. WARNING: The BioGRID REST service updates to the new version at 12pm GMT on the 2nd of each month, meaning that you may receive 'old' data for up to a day for previously performed queries - even if http://webservice.thebiogrid.org/resources/version indicates the new version is being used.| | ||
| + | ====== Deprecated Parameters ====== | ||
| + | |||
| + | ^Parameter^Type^Default^Valid Values^Description^ | ||
| + | |sourceDatabaseList|string|“BioGRID”|Pipe-separated list of database names, currently including BioGRID, INTACT, MINT, DIP|Only interactions with Source Database on this list will be returned.| | ||
| + | |sourceDatabaseIdList|string|empty|Pipe-separated list of source database identifiers|Interactions with a source database interaction ID in the list will be included in the results. The source database for the identifier must also be selected using sourceDatabaseList.| | ||
| + | These parameters are still available at our old web service location at: **sce-bio-c02577.bio.ed.ac.uk:8080/BiogridRestService** | ||