Genboree

HELP TOPIC: "8.A REST API – Resource IDs"




 
8.A.1. Introduction:

The Genboree API operates on resources which correspond to data entities or collections of entities stored within Genboree. Genboree resources range from those of user genomic data—annotations, chromosomes, tracks, etc—but can also include other types of data, such as user groups, user databases, project pages, etc.

Each resource must have at least 1 unique identifier, and there must be some way of indicating the location of the resource. By using Uniform Resource Locators (URLs) for our identifiers, we satisfy both the unique and locatability criteria.

The URLs have a general form, with several distinct parts:

Resource URI
({rsrcURI})
Auth.
Parameters
http://{genbHost}/{rsrcPath}?{rsrcParams} {authParams}

  • - The core of the resource URL is the {rsrcURI}, which is everything but the authorization parameters:
    • - {genbHost} is the host where Genboree is running
      (e.g. www.genboree.org)
    • - {rsrcPath} is the path identifying the resource. See below.
      (e.g. /REST/v1/grp/{grpName}/db/{dbName}/tracks)
    • - {rsrcParams} are any parameters for the resource, generally to modify the representation received or sent. Generally optional.

  •   - Appended to the {rsrcURI} are the 3 required parameters Genboree uses to authorize and authenticate the user accessing/modifying the resource. See the REST API - Authorization page for more detail.


 
8.A.2. Resource Paths (rsrcPath)

The path of the resource URL is the key component indicating which resource on the Genboree host you wish to operate on. In effect, the path describes the location and name of the resource, similar to the path to a file on your computer.

The structure of the path is highly hierarchical, and corresponds to how Genboree data entities are nested and how they are presented to the user in the Genboree UI.

The path is also highly descriptive, in that dynamic fields are preceded by a static category indicating what the field represents. Furthermore, plurality is used to indicate collections of resources as opposed individual entities.

  •    A specific resource may be addressed by more than one {rsrcPath}. The path used provides some context for accessing the data entity, which can be used to process the request where appropriate.

Finally, the API is versioned, which is reflected in the /v1 following the common /REST prefix. This facilitates simultaneous support for newer, but incompatible, versions of the API and provides continued support for any older resource identifiers in use.

 

8.A.2.1. Resource Path Table

The table below lists the resources exposed in the current version of the Genboree REST API. New resources will be added over time, so check back often. If you wish to request exposure of certain Genboree data entities, please contact us.

Parameters affecting the representation or filtering collections of entities are indicated in blue. Following a parameter will be information on whether it is optional and if so what default value [if any] will be used; the phrase multiple ok indicates the parameter can be provided more than once if multiple values are useful (e.g. multiple landmarks specifying several regions from which to get annotations); the detailed flag is used to indicate that a detailed representation is or is not desired in the response.

 Resource: Users
Resource Path (rsrcPath) Description
/REST/v1/usr/{usr}/grps Collection of groups to which user {usr} belongs.
detailed » [optional; default: 'no']
/REST/v1/usr/{usr}/grp/{grp} A group to which user {usr} belongs.
 Resource: User Groups
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp} A user group.
/REST/v1/grp/{grp}/dbs Collection of databases within group {grp}.
/REST/v1/grp/{grp}/prjs Collection of projects within group {grp}.
/REST/v1/grp/{grp}/usrs Collection of users within group {grp}.
/REST/v1/grp/{grp}/usr/{usr} A user within {grp}.
/REST/v1/grp/{grp}/usr/{usr}/role A user's role within {grp}.
/REST/v1/grp/{grp}/usr/{usr}/unlockedResources The unlocked resources within {grp}.
 Resource: User Databases
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}/db/{db} A database within group {grp}.
/REST/v1/grp/{grp}/db/{db}/eps Collection of entrypoints (e.g. chromosomes) within database {db} within group {grp}.
/REST/v1/grp/{grp}/db/{db}/trks Collection of tracks within database {db} within group {grp}.
detailed » [optional; default: 'no']
/REST/v1/grp/{grp}/db/{db}/seq DNA sequence for database {db} within group {grp}.
landmark » [optional; multiple ok; default: absent;
e.g. 'chr1:1234-5678']
 Resource: Database Files
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}/db/{db}/files A collection of data file belonging to database {db}.
/REST/v1/grp/{grp}/db/{db}/file/{fileName} A data file belonging to database {db}.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/data The contents of the file {fileName}.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/label The label of the file {fileName}.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/description The description of the file {fileName}.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/date The date of the file {fileName}.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/archived Indicates whether the file {fileName} is archived.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/autoArchive Indicates whether the file {fileName} will be autoArchived.
/REST/v1/grp/{grp}/db/{db}/file/{fileName}/hide Indicates whether the file {fileName} is hidden.
 Resource: User Projects
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}/prj/{prj} A project within group {grp}.
/REST/v1/grp/{grp}
/prj/{prj}/title
Title text/html for a project within group {grp}.
/REST/v1/grp/{grp}
/prj/{prj}/description
Description text/html for a project within group {grp}.
/REST/v1/grp/{grp}
/prj/{prj}/customContent
Custom (free-form) content for a project within group {grp}.
/REST/v1/grp/{grp}
/prj/{prj}/news
Collection of ALL news items for a project within group {grp}.
/REST/v1/grp/{grp}
/prj/{prj}/links
Collection of ALL links for a project within group {grp}.
/REST/v1/grp/{grp}
/prj/{prj}/quickLinks
Collection of ALL quick-links for a project within group {grp}.
 Resource: Entrypoints (e.g. chromosomes)
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}
/db/{db}/ep/{ep}
An entrypoint from database {db} within group {grp}.
 Resource: Annotation Tracks
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}
A track from database {db} within group {grp}.
detailed » [optional; default: 'no']
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/url
URL associated with track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/urlLabel
URL label text for track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/description
Description text for track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/templateUrl
URL associated with track {trk} from template database {db}
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/templateUrlLabel
URL label text for track {trk} from template database {db}
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/templateDescription
Description text for track {trk} from the template database {db}
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/style
The user-definied style of the track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/display
The user-definied display type associated with track {trk} from user database {db} within user group {grp}. Should be one of: ()
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/color
The user-definied display color or the track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/rank
The user-definied sort order of the track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/defaultStyle
The group default style of the track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/defaultDisplay
The group default display type associated with track {trk} from user database {db} within user group {grp}. Should be one of: ()
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/defaultColor
The group default display color of the track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/defaultRank
The group default sort order for the track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/classes
Collection of classes/categories associated with track {trk} from user database {db} within user group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/annoAttributes
Collection of user-defined attributes/properties associated with an annotation for track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/bigBed
BigBed file for the track {trk}
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/bigWig
BigWig file for the track {trk}
 Resource: Track Attributes
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/attributes
Collection of user-defined attributes associated with track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/attribute/{attribute}/value
The value for attribute with the name {attribute} associated with track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/attribute/{attribute}/display
The user-defined display settings for attribute with the name {attribute} associated with track {trk} from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/attribute/{attribute}/defaultDisplay
The group default display settings for attribute with the name {attribute} associated with track {trk} from database {db} within group {grp}.
 Resource: Annotations
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/annos
Collection of annotations within track {trk} from database {db} within group {grp} returned in various formats depending on value of format parameter.
layoutName » [only when format=layout; default: absent]
landmark » [optional; multiple ok; default: absent;
e.g. 'chr1:1234-5678']
format » [lff, gff, bed, bed3col, wig, fwig, vwig, layout]
/REST/v1/grp/{grp}
/db/{db}/trks/annos
Collection of annotations within tracks (listed in request body) from database {db} within group {grp} returned in various formats depending on value of format parameter.
layoutName » [only when format=layout; default: absent]
landmark » [optional; multiple ok; default: absent;
e.g. 'chr1:1234-5678']
/REST/v1/grp/{grp}
/db/{db}/trk/{trk}/annos/count
Count of number of annotations within track from database {db} within group {grp}.
landmark » [optional; multiple ok; default: absent;
e.g. 'chr1:1234-5678']
/REST/v1/grp/{grp}
/db/{db}/trks/annos/count
Count of number of annotations withing tracks (listed in request body) from database {db} within group {grp}.
landmark » [optional; multiple ok; default: absent;
e.g. 'chr1:1234-5678']
 Resource: Tabular Layouts
Resource Path (rsrcPath) Description
/REST/v1/grp/{grp}
/db/{db}/annos/layouts
Collection of saved tabular layouts from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/annos
/layout/{layout}
The saved tabular layout representation from database {db} within group {grp}.
/REST/v1/grp/{grp}
/db/{db}/annos
/layout/{layout}
/attribute/{attribute}
A single attribute from the saved tabular layout {layout} from database {db} within group {grp}. The userId, created, and modified attributes are all read-only.
 Resource: Queryable
Resource Path (rsrcPath) Description
/REST/v1/queryable

/REST/v1/grp/{grp}
/queryable

/REST/v1/grp/{grp}
/db/{db}/queryable

A list of all of the queryable resources available. The response object contains a template URI attribute for each resource, and if the query was performed with either the second or third form of the URI listed here, the {db} and / or {grp} will be automatically replaced with their values in this attribute.
/REST/v1/grp/{grp}
/db/{db}/{*}/queryable
The information about a queryable resource (specified by the path {*}) including: whether or not the resource specified is a queryable resource, its name and human readable (pretty) name, its template URI, and the attributes that can be queried against for that particular resource.


 

 

 


Bioinformatics Research Laboratory © 2001-2024 Baylor College of Medicine
Bioinformatics Research Laboratory
(400D Jewish Wing, MS:BCM225, 1 Baylor Plaza, Houston, TX 77030)