Resource Index API and JSON

Resource Index API Revision

• Resource Index REST Web Service User Guide

Endpoints

* /resource_index/search
* /resource_index/resources
* /resource_index/resources/{resource_id}
* /resource_index/resources/{resource_id}/elements/{element_id}

Get elements where annotations exist for given classes

* /resource_index/search?classes={ontology_acronym;class_id,ontology_acronym1;class_id1}
# The following will add a list of annotations for each class
* /resource_index/search?classes={ontology_acronym;class_id,ontology_acronym1;class_id1}&include_annotations=true

Paul: The things separated by ';' are ontology acronym/class id pairs because the class ids are not unique across all ontologies. The comma-separatation indicates a list of these pairs. However, after thinking about it, it would probably be better to use the following instead classes[acronym1][classid1,classid2,classid3]&classes[acronym2][classid1,classid2] This will give us a hash in Sinatra called 'concepts' in the params variable. We'll need to convert the classid1,classid2 into an array by splitting the values. This also lines up with how we'll be handing nested values when doing POSTs or PUTs elsewhere.

Parameters

Filtering & query behavior

* ontologies={acronym1,acronym2,acronym3}
* semantic_types={semType1,semType2,semType3}
* max_level={0..N}
* mapping_types={automatic,manual}
* resources={resource1,resource2}
* exclude_numbers={true|false}
* minimum_match_length={0..N}
* include_synonyms={true|false}
* include_offsets={true|false}
* mode={union|intersection}

Stop words

* exclude_words={word1,word2,word3}
* excluded_words_are_case_sensitive={true|false}

Response Formats

Notes

• ... indicates that similar items to the previous will continue in the list
• // indicates a comment (text after this should not appear in response)
• {value1|value2} indicates expected values:
• Old to new context name mappings
  • mgrepContext: direct
  • mappingContext: mapping
  • isaContext: hierarchy

Search

{
    "GEO": {
        "annotations": [
            {
                "annotatedClass": {
                    "id": "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Melanoma", 
                    "ontology": "NCIT"
                }, 
                "annotationType": "direct",
                "elementField": "GEO_summary", 
                "elementId": "GSE20469", 
                "from": 20, 
                "to": 25
            }
        ], 
        "annotatedElements": {
            "GSE20469": {
                "GEO_organism": {
                    "text": "1132/NCBITaxon:9606", 
                    "weight": 1,
                    "associatedOntologies": [
                        1132
                    ]
                }, 
                "GEO_summary": {
                    "text": "Metastatic melanoma is difficult to treat and is resistant to most current therapies. .....", 
                    "weight": 0.8,
                    "associatedOntologies": []
                }, 
                "GEO_title": {
                    "text": "A novel way for enriching human melanoma precursor cells to identify cellular targets for antineoplastic therapy", 
                    "weight": 1,
                    "associatedOntologies": []
                }, 
                "GEO_uid": {
                    "text": "200020469", 
                    "weight": 0,
                    "associatedOntologies": []
                }
            }
        }
    }
}

Resources

[
  {
    "resourceName": "Gene Expression Omnibus DataSets",
    "resourceId": "GEO",
    "mainContext": "GEO_title",
    "resourceURL": "http://www.ncbi.nlm.nih.gov/geo/",
    "resourceElementURL": "http://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=",
    "resourceDescription": "A gene expression/molecular abundance repository supporting  MIAME compliant data submissions, and a curated, online resource for gene expression data browsing, query and retrieval.",
    "resourceLogo": "http://rest.bioontology.org/ri_images/GEO.jpg",
    "lastUpdateDate": "2012-03-09 02:13:30.0 PST",
    "totalElements": 31483
  },
  ...
]

Resources JSON Schema

JSON-schema for description and validation of REST JSON responses.

• http://tools.ietf.org/id/draft-zyp-json-schema-03.html
• http://tools.ietf.org/html/draft-zyp-json-schema-03

  {
    "type": "array",
    "title": "resources",
    "description": "An array of Resource Index resource objects.",
    "items": { "type": "object" }
  }

  {
    "type": "object",
    "title": "resource",
    "description": "A Resource Index resource.",
    "additionalProperties": false,
    "properties": {
      "resourceName": { "type": "string", "required": true },
      "resourceId": { "type": "string", "required": true },
      "mainContext": { "type": "string", "required": true },
      "resourceURL": { "type": "string", "format": "uri", "required": true },
      "resourceElementURL": { "type": "string", "format": "uri" },
      "resourceDescription": { "type": "string" },
      "resourceLogo": { "type": "string", "format": "uri" },
      "lastUpdateDate": { "type": "string", "format": "datetime" },
      "totalElements": { "type": "number" }
    }
  }

Elements

[
    {
        "id": "GSE20469",
        "fields": {
            "GEO_title": {
                "weight": 1,
                "text": "A novel way for enriching human melanoma precursor cells to identify cellular targets for antineoplastic therapy",
                "associatedOntologies": [ ]
            },
            "GEO_summary": {
                "weight": 0.8,
                "text": "Metastatic melanoma is difficult to treat and is resistant to most current therapies. ....",
                "associatedOntologies": [ ]
            },
            "GEO_organism": {
                "weight": 1,
                "text": "1132/NCBITaxon:9606",
                "associatedOntologies": [ 1132 ]
            },
            "GEO_uid": {
                "weight": 0,
                "text": "200020469",
                "associatedOntologies": [ 1 ]
            }
        }
    },
    ...
]

Elements JSON Schema

JSON-schema for description and validation of REST JSON responses.

• http://tools.ietf.org/id/draft-zyp-json-schema-03.html
• http://tools.ietf.org/html/draft-zyp-json-schema-03

{
  "type": "array",
  "title": "elements",
  "description": "An array of Resource Index element objects.",
  "items": { "type": "object" }
}

{
    "type": "object",
    "title": "element",
    "description": "A Resource Index element.",
    "additionalProperties": false,
    "properties": {
        "id": { "type": "string", "required": true },
        "fields": { "type": "object", "required": true }
    }
}

{
    "type": "object",
    "title": "element_field",
    "description": "A Resource Index element field.",
    "additionalProperties": false,
    "properties": {
        "text": { "type": "string", "required": true },
        "associatedOntologies": { "type": "array", "required": true },
        "weight": { "type": "number", "required": true }
    }
}