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

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:

• - 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.

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.

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.