Repository navigation
Checker API documentation
This page provides the documentation of the Sandbox checker API. The purpose for this API is to provide a machine readable interface to match glycan structures with one of the GlycoTrees and provide caveats that may point to structural errors. The API can be used to check glycan structures before submitting them to databases. A public webpage for testing the webservice is available.
Content
Supported HTTP request method: GET
Base URL: https://glygen.ccrc.uga.edu/sandbox/api/checkers.php
Parameter:
- glycoct (mandetory): Glycan sequence in GlycoCT format. The GlycoCT needs to linearized by replace line breaks ("\n") with white spaces (" "). On Windows system the carriage return ("\r") should be removed.
- type (mandetory): GlycoTree that the structure should be matched agains. Possible values are "N" (N-linked glycan structures) and "O" (Mucin type O-linked structures)
- enz (optional): A flag ("true"/"false") to add enzyme information into the response. Default value is "true".
- related (optional): A flag ("true"/"false") to add to add a list of related structures (enzymatic precursors or successors) into the response. Default value is "false"
- debug (optional): A flag ("true"/"false") that changes the response into a non-JSON text format with verbose debug information about the matching process. This is not meant for production but for exploring errors and problems. Default value is "false".
Example URI:
https://glygen.ccrc.uga.edu/sandbox/api/checkers.php?glycoct=RES+1b%3Ax-dglc-HEX-1%3A5+2s%3An-acetyl+3b%3Ab-dglc-HEX-1%3A5+4s%3An-acetyl+5b%3Ab-dman-HEX-1%3A5+6b%3Aa-dman-HEX-1%3A5+7b%3Ab-dglc-HEX-1%3A5+8s%3An-acetyl+9b%3Ab-dgal-HEX-1%3A5+10b%3Ab-dglc-HEX-1%3A5+11s%3An-acetyl+12b%3Ab-dgal-HEX-1%3A5+13b%3Aa-dman-HEX-1%3A5+14b%3Ab-dglc-HEX-1%3A5+15s%3An-acetyl+16b%3Ab-dgal-HEX-1%3A5+17b%3Aa-dgal-HEX-1%3A5+18b%3Aa-lgal-HEX-1%3A5%7C6%3Ad+LIN+1%3A1d%282%2B1%292n+2%3A1o%284%2B1%293d+3%3A3d%282%2B1%294n+4%3A3o%284%2B1%295d+5%3A5o%283%2B1%296d+6%3A6o%282%2B1%297d+7%3A7d%282%2B1%298n+8%3A7o%284%2B1%299d+9%3A6o%284%2B1%2910d+10%3A10d%282%2B1%2911n+11%3A10o%284%2B1%2912d+12%3A5o%286%2B1%2913d+13%3A13o%282%2B1%2914d+14%3A14d%282%2B1%2915n+15%3A14o%284%2B1%2916d+16%3A16o%283%2B1%2917d+17%3A1o%286%2B1%2918d&type=N&enz=false&related=false&debug=false
Response of the web-service is a JSON object with the mapping information to the GlycoTree and a list of caveats and enzymatic rule violations.
{
"glytoucan_ac":"undetermined",
"temp_id":"NTEMP9892a61",
"rule_violations":{
{
"rule_id":1,
"instance":1,
"focus":"N7",
"enzyme":"Q812F8",
"other_residue":"N2",
"polymer":"NULL",
"taxonomy":"Mus musculus",
"logic":"transfer of residue [focus] by [enzyme] in [taxonomy] requires residue [other_residue]",
"refs":"PMID: 1533386",
"comment":"GNT obligate order",
"status":"active",
"class":"biosynthesis",
"description":"positive glycosyltransferase acceptor substrate specificity",
"assertion":"transfer of residue N7 (β-D-GlcpNAc) by Q812F8 in Mus musculus requires residue N2 (β-D-GlcpNAc)"
},
...
],
"caveats":[
{
"msg":"One or more residues in NTEMP9892a61 is abiotic. Thus, NTEMP9892a61 is itself abiotic (e.g., chemically synthesized or mis-characterized):residue N201 (α-D-Fucp) has an abiotic absolute configuration"
},
...
],
"residues":[
{
"residue_id":"NA",
"name":"GlcNAc",
"anomer":"b",
"absolute":"D",
"ring":"p",
"parent_id":"0",
"site":"0",
"form_name":"GlcpNAc",
"glycoct_index":"1",
"residue_name":"N-glycan_core_D-GlcNAc_A",
"notes":"validated by Qrator",
"glycotree": "N-glycan",
"enzymes":null
}
...
]
}
- glytoucan_ac: GlyTouCan accession of the submitted glycan. If the accession is not known it will be "undetermined"
- temp_id: Temporary ID for the glycan assigned by the system. Used for debug purposes only.
- rule_violoations: A list of enzymatic rules that this structures violates. The rules format will be explained below.
- caveats: A list of human readable messages describing the problems of the structure caused by the rules violation.
- residues: A list of residues of the structures and their mapping to the GlycoTree. The residues will be explained below.
The rule violation section of the JSON describes the rules that the submitted structure did not match.
{
"rule_id":1,
"instance":1,
"focus":"N7",
"enzyme":"Q812F8",
"other_residue":"N2",
"polymer":"NULL",
"taxonomy":"Mus musculus",
"logic":"transfer of residue [focus] by [enzyme] in [taxonomy] requires residue [other_residue]",
"refs":"PMID: 1533386",
"comment":"GNT obligate order",
"status":"active",
"class":"biosynthesis",
"description":"positive glycosyltransferase acceptor substrate specificity",
"assertion":"transfer of residue N7 (β-D-GlcpNAc) by Q812F8 in Mus musculus requires residue N2 (β-D-GlcpNAc)"
}
- rule_id: ID of the rule type (e.g., rule that requires another residue to be added before a specific residue)
- instance: ID of the rule instance
- assertion: Human readable text of the rule
The residue section shows the mapping of the glycan residues to the selected GlycoTree. The section is an array of residue objects with the following structures:
{
"residue_id": "N50",
"name": "Gal",
"anomer": "a",
"absolute": "D",
"ring": "p",
"parent_id": "N6",
"site": "3",
"form_name": "Galp",
"glycoct_index": "17",
"residue_name": "N-glycan_a-D-Galp_50",
"notes": "validated by Qrator",
"glycotree": "N-glycan",
"enzymes": null
}
- residue_id: GlycoTree internal residue ID. Can be used for linking.
- name: IUPAC basetype name of the monosaccharide. Or superclass if no basetype is defined.
- anomer: Anomeric configuration of the monosaccharide. "x" for unknown anomer and "o" for open ring sugars.
- absolute: Absolute configuration of the monosaccharide.
- ring: Ring configuration of the monosaccharide. "x" for unknown ring size and "ol" for open ring sugars.
- parent_id: Parent residue of the monosaccharide. Will be "0" for the root residue.
- site: Linkage position at the parent residue.
- form_name: Formal name of the residue (without absolute configuration and anomer)
- glycoct_index: Residue ID in GlycoCT. Will not be present if residue can not be mapped. The index will be used as residue_id instead.
- residue_name: Name of the residue in GlycoTree. If the residue can not be mapped this property is absent.
- glycotree: Name of the GlycoTree the residue was mapped to.
- enzymes: List of enzymes that can add the residue. If the enz option in the webservice call is set to false the list will be null.
Please Note: If a residue can not be mapped with the GlycoTree (e.g. incorrect anomer, ring, configuration, basetype, or linkage position at the parent) the following changed configuration will be used to indicate it:
{
"residue_id": "1",
"glycotree": "none",
}
- residue_id: Will be using the numerical GlycoCT index instead of the alphanumerical residue_id from GlycoTree.
- glycotree: The GlycoTree name will be set to "none".
If an error occurs there will a an error list added to the top level of the JSON:
{
...
"error": [
{
"type": "input error",
"message": "GlycoCT is absent"
},
{
"type": "input error",
"message": "glycan type (X) is not supported"
},
{
"type": "decoding error",
"message": "GlycoCT could not be decoded"
}
]
Each error object consists of an error type (type) and a human readable message. The error types are:
input error For missing or invalid data in the web service all:
- No GlycoCT was submitted ("GlycoCT is absent")
- No GlycoTree type was submitted ("glycan type () is absent")
- Invalid GlycoTree type was submitted ("glycan type (...) is not supported")
decoding error Error if the GlycoCT is invalid or contains errors.