The following examples use Python and the requests package to access resources of the CREDO web service. This package can easily be installed using pip with $ sudo pip install requests. There is a plethora of other tools and libraries however that can be used to access the RESTful web service.

Quickstart

Here is a detailed example of how to fetch data for a single chemical component. The accept header is used to let the resource know that the client expects a JSON response. Every web service resource returns a 200 status code on success. Status codes starting with 4 (e.g. 400) are returned if the client seems to have erred. This happens if an invalid structure is uploaded, for example. The web service tries to return informative error messages where possible.

Important The web service automatically tries to decode URL query parameters. Therefore you should make sure that submitted strings either do not contain reserved characters such as plus and forward slashes or are properly encoded (percent-encoding).

Inspecting the response

Every JSON response from the CREDO web service contains a metadata and data object. The first is a single list that describes the column name and data type for each column in the list of returned data values.

Uploading files

Some CREDO resources accept file uploads such as retrieving all chemical components similar to a query structure in SDF format through USR similarity.

The following section describes available API resources. This documentation is still work in progress and will be extended over time to describe other available resources. Curly brackets represent variables whereas URL parts surrounded by square brackets are optional. The second column of the query parameters table contains information about possible default values or what kind of value should be used for the given parameter - 't' should be used for Boolean values. Red labels indicate mandatory parameters. Parameters cannot be combined unless explicitly stated otherwise. The base URL for all resources is http://marid.bioc.cam.ac.uk/credo.

Structures

GET /structures/{pdb} application/json Returns a single PDB entry.
GET /structures/[page/{page}] application/json Returns a set of PDB entries.
Implementation Notes

The {page} parameter defaults to 1 and /chemcomps/ is the same as /chemcomps/page/1.

Query parameters

This resource allows all structure column expressions.

het_id None Return only PDB entries that contain a ligand with the given HET-ID.
uniprot None Return only PDB entries that contain a polypeptide having the given UniProt accession.
GET /structures/sim/(ts)/[page/{page}] application/json Returns a set of PDB entries using similarity.
Endpoints
ts
PostgreSQL text search of the abstracts associated with PDB entries.
Query parameters

This resource allows all structure column expressions.

tsquery Required The text query used for searching.
plain t If true, the server will automatically convert the text query in a suitable form, otherwise it is assumed that the query is already in a valid PostgreSQL full text search syntax.

Biomolecules

Chains

GET /chains/{chain_id} application/json Returns a single chain.
GET /chains/{path} application/json Returns the chain having the specified path.
GET /chains/[page/{page}] application/json Returns a paginated set of chains.
Implementation Notes

The {page} parameter defaults to 1 and /chains/ is the same as /chains/page/1.

Query parameters

This resource allows all chains column expressions.

structure_id Integer Returns all chains belonging to the structure having the specified structure_id.
phenotype_id Integer Returns all polypeptide chains that contain a residue having a mapped variation that is linked to an EnsEMBL phenotype_id.
oligonucleotides Boolean Returns all DNA/RNA (or hybrid) chains.
dna Boolean Returns all DNA chains.
rna Boolean Returns all RNA chains.
polysaccharides Boolean Returns all polysaccharide chains, i.e. every chain having polymer type polysaccharide(D).
uniprot None Returns all polypeptide chains matching the given UniProt accession.
go None Returns all polypeptide chains matching the given GO accession.
kinases Boolean Returns all kinases from the UniProt kinase set that can be found in CREDO.
pmatch None Returns all chains matching the given CREDO path expression.

Ligands

GET /ligands/{ligand_id} application/json Returns a single ligand.
GET /ligands/[page/{page}] application/json Returns a paginated set of ligands.
Implementation Notes

The {page} parameter defaults to 1 and /ligands/ is the same as /ligands/page/1.

Query parameters

This resource allows all ligand column expressions.

recent Boolean Returns the most recent ligands in CREDO.
kinases Boolean Returns all ligands that are in contact with protein kinases.
fragments Boolean Returns the ligands that are true fragments, i.e. conform to the rule of three.
het_id None Returns the ligands of the chemical component with the given HET-ID.
structure_id Integer Returns the ligands of the PDB entry having the specified structure_id.
chembl_id None Returns the ligands of the chemical component with the given ChEMBL identifier.
phenotype_id Integer Returns all ligands that are interacting with a residue having a mapped variation that is linked to an EnsEMBL phenotype_id.
uniprot None Returns all ligands that are in contact with a protein having the given UniProt accession.
cath None Returns all ligands that are in contact with a protein whose binding site has the given CATH domain accession.
xbonds Boolean Returns all ligands that have halogen bonds.
metalcomplexes Boolean Returns all ligands that form metal complexes, including metal ions of course.

Chemical Components

GET /chemcomps/{het_id} application/json Returns a single chemical component.
GET /chemcomps/[page/{page}] application/json Returns a paginated set of chemical components.
Implementation Notes

The {page} parameter defaults to 1 and /chemcomps/ is the same as /chemcomps/page/1.

Query parameters

This resource allows all chemical component column expressions.

substruct None Return only chemical components that contain the specified substructure SMILES string.
superstruct None Return only chemical components that are contained by the specified superstructure SMILES string.
smarts None Return only chemical components that match the given SMARTS pattern.
fragment_id Integer Return only chemical components that contain the fragment with the given CREDO fragment identifier.
GET /chemcomps/sim/(fp,trigram)/[page/{page}] application/json Returns a set of chemical components that are similar to a chemical query (2D).
Endpoints
fp
Topological fingerprint similarity
trigram
PostgreSQL trigram similarity
Query parameters

This resource allows all chemical component column expressions.

smiles Required The query structure in SMILES format.
tk rd Toolkit from which the fingerprint should be used: either rd for RDKit or oe for OpenEye.
fptype circular Fingerprint type to use.
metric tanimoto Similarity metric to use.
threshold 0.5 Similarity threshold for searching.
POST /chemcomps/sim/usr/[page/{page}] application/json Performs a USR/USRCAT search with the given options and returns the most similar chemical components.
Query parameters

This resource allows all chemical component column expressions. Either a chemical structure must be provided as file or a file of 60 USRCAT moments, one per line.

file file The uploaded file (OEB, PDB,SDF) will be used to calculate the USRCAT moments.
moments file A file containing the 60 USRCAT moments, one per line, that will be used to search the chemical components.
usrcat t,f Perform a USRCAT search instead of traditional USR.
probe_radius 1.0 Radius of the bounding box that is used for the USR index. Must be less than or equal to 2.0.
ow,hw,rw,aw,dw 0.25 Pharmacophore weights for USRCAT moments.
threshold 0.5 Similarity threshold for searching.
Example

Fragments

GET /fragments/{fragment_id} application/json Returns a single (chemical component) fragment.
GET /fragments/[page/{page}] application/json Returns a paginated set of fragments.
Implementation Notes

The {page} parameter defaults to 1 and /fragments/ is the same as /fragments/page/1.

Query parameters

This resource allows all fragment column expressions.

het_id None Return only fragments that are derived from the chemical component with the given HET-ID.

Contacts

GET /contacts/ application/json Returns the contacts of an entity.
Implementation Notes

This resource can be used to retrieve contacts from CREDO. The biomolecule identifier is mandatory.

Query parameters

This resource allows all contact column expressions.

biomolecule_id Integer The biomolecule identifier the entity is part of. Always required to retrieve contacts from CREDO.
ligand_id Integer Ligand identifier from CREDO.
Example

Binding sites

GET /bindingsites/[page/{page}] application/json Returns a paginated set of protein-ligand binding sites.
Implementation Notes

The {page} parameter defaults to 1 and /bindingsites/ is the same as /bindingsites/page/1.

Query parameters

This resource allows all ligand and binding sites column expressions. Supports the same parameters as the ligands resource.

Protein-protein Interfaces

Protein-nucleic acid Grooves

Ligand-ligand interactions

GET /ligligints/[page/{page}] application/json Returns a paginated set of ligand-ligand interactions.
Implementation Notes

The {page} parameter defaults to 1 and /ligligints/ is the same as /ligligints/page/1.

Query parameters

This resource allows all ligand-ligand interaction column expressions.

substrates Boolean Return all ligand-ligand interactions where one of the ligands is a substrate bound to its enzyme.
products Boolean Return all ligand-ligand interactions where one of the ligands is a product bound to its enzyme.
enzymecmpds Boolean Return all ligand-ligand interactions where one of the ligands is either a substrate or product bound to its enzyme.
drugtargetints Boolean Return all ligand-ligand interactions where one of the ligands is the drug-target's inhibitor.
druglikes Boolean Return all ligand-ligand interactions where both ligands are drug-like.
het_id None Return all ligand-ligand interactions where at least one ligand matches the given HET-ID.
pmatch None Returns all ligand-ligand interactions matching the given CREDO path expression.

Ligand-nucleic acid interactions

GET /lignucints/[page/{page}] application/json Returns a paginated set of ligand-nucleic interactions.
Implementation Notes

The {page} parameter defaults to 1 and /lignucints/ is the same as /lignucints/page/1.

Query parameters

This resource allows all ligand-nucleic acid interaction column expressions.

druglike Boolean Return all ligand-nucleic acid interactions where the ligand is drug-like.
het_id None Return all ligand-nucleic acid interactions where the ligand matches the given HET-ID.
appdrugs Boolean Return all ligand-nucleic acid interactions where the ligand is an approved drug.
pmatch None Returns all ligand-ligand interactions matching the given CREDO path expression.

Variations

GET /variations/[page/{page}] application/json Returns a paginated set of variations.
Implementation Notes

The {page} parameter defaults to 1 and /variations/ is the same as /variations/page/1.

Query parameters

This resource allows all variation column expressions.

chain_id Integer Return all variations linked to residues that are part of the chain with the given chain_id.
ligand_id Integer Return all variations linked to residues that are in contact with the ligand having the given ligand_id.
phenotype_id Integer Return all variations linked to EnsEMBL phenotype with the given identifier.

Identifying contacts in uploaded structures

POST /credo/contacts/{format} text/plain, application/json, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Identifies all contacts in the posted structure and returns them in the specified format.

This feature is currently only available for local users.
The CREDO web service can be used to identify all contacts in an uploaded structure. To do this, you will need to POST the structure to the resource http://vahi.bioc.cam.ac.uk/credo/contacts/. Only the PDB structure format is supported for uploaded files at this point. Uploaded structures are only kept in memory and not stored on the server.

Formats
tsv
Returns the structural interaction fingerprints as tab-separated text.
json
Returns the structural interaction fingerprints in JSON format. The returned data is accessible as a Python dictionary through either response.json or as raw text trough response.text.
xlsx
Returns the structural interaction fingerprints as Microsoft Excel 2007+ spreadsheet.
pym
Returns a PyMOL script to visualise the interactions. The script is accessible through response.text.
Query parameters

The resource also supports a couple of optional parameters. The pdb_chain_id and res_num parameters should be used to restrict the search to the entity of interest, for instance a single chain or ligand.

structure Required The macromolecular structure to be used for contact identification. Only the PDB format is currently supported.
title taken from filename Title to be used for this structure - will appear in the JSON data and Excel spreadsheet.
pdb_chain_id None Only return interactions involving atoms belonging to the chain with this identifier.
res_num None Only return interactions involving atoms belonging to a residue that has this residue number.
Example

Here is an example that demonstrates how a single structure can be uploaded to identify all contacts that chain B has with all other atoms in the structure. In this case, the response will contain the structural interaction fingerprints in JSON format.