HELP TOPIC: "8.B REST API – Methods"

A small set of methods, uniform for all resources, is a cornerstone of REST. Other approaches to web services can amount to complex ways of performing many varied operations on resources; i.e. they implement remote procedure calls (RPCs) of object-specific methods on remote objects, which is not at all uniform.

The Genboree API makes use of the small set of methods defined by HTTP for manipulating resources on the web. These methods let you retrieve resources, create new resources and update existing ones, and delete existing resources. This 'C.R.U.D.' set of fundamental operations is also using in the database world, which similarly focusses on the storage and retrieval of data resources.

The operations supported on Genboree resources are those of HTTP, and are made via the request method in the HTTP request to the API URL.

• - GET » get a representation of the resource.
• - PUT » put a new resource or put a change to an existing resource on the server.
• - DELETE » delete an existing resource.
• - POST » (currently unused, but reserved for appropriate ROA-founded extension)

Many resources do not support ALL of the methods; this may be because the method is not implemented yet for that resource, or the method is inappropriate for the resource, or the method has been judged too dangerous to expose in the API. In all cases, however, the supported methods are a subset of those of HTTP.

Section 8.B.3 below discusses the return values of the methods.

The table below indicates the supported methods for the resources exposed in the current version of the Genboree REST API. The resources are indicated by their rsrcPath component. New methods (and resources) will be added over time, so check back often. If you wish to request exposure of certain Genboree data entities, please contact us.

Descriptions of the resources can be found in Section 8.A.2.1 - Resource Paths Table.

`

Resource: Users
Resource Path (rsrcPath)	Currently Supported Methods
/REST/v1/usr/{usr}/grps	GET » collection of user's groups
/REST/v1/usr/{usr}/grp/{grp}	GET » group
Resource: User Groups
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp}	GET » group PUT » create a new group or update existing group (in request body)
/REST/v1/grp/{grp}/dbs	GET » collection of databases
/REST/v1/grp/{grp}/prjs	GET » collection of projects PUT » new project (in request body) into group
/REST/v1/grp/{grp}/usrs	GET » collection of users PUT » existing users (in request body) into group as subscriber
/REST/v1/grp/{grp}/usr/{usr}	GET » user PUT » existing user into group as subscriber DELETE » remove user from group
/REST/v1/grp/{grp}/usr/{usr}/role	GET » user role in group PUT » existing user into group with role (in request body) DELETE » remove user from group
/REST/v1/grp/{grp}/usr/{usr}/unlockedResources	GET » collection of unlocked resources for the group PUT » resources to be unlocked (in request body) DELETE » remove a resource from the unlocked resources
Resource: User Databases
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp}/db/{db}	GET » database PUT » a new database
/REST/v1/grp/{grp}/db/{db}/eps	GET » collection of entrypoints (chromosomes) PUT » new entrypoints
/REST/v1/grp/{grp}/db/{db}/trks	GET » collection of tracks
/REST/v1/grp/{grp}/db/{db}/seq	GET » sequence
Resource: User Projects
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp}/prj/{prj}	GET » project PUT » a new project into group or a new name for existing project [rename], or copy a project (referece to source project in request body) DELETE
/REST/v1/grp/{grp}/prj/{prj}/title	GET » project title PUT » a new project title (in request body)
/REST/v1/grp/{grp}/prj/{prj}/description	GET » project description PUT » a new project description (in request body)
/REST/v1/grp/{grp}/prj/{prj}/customContent	GET » project custom content PUT » a new project custom content (in request body)
/REST/v1/grp/{grp}/prj/{prj}/news	GET » collection of ALL project news items PUT » a new collection of news items (in request body)
/REST/v1/grp/{grp}/prj/{prj}/links	GET » collection of ALL project links PUT » a new collection of project links (in request body)
/REST/v1/grp/{grp}/prj/{prj}/quickLinks	GET » collection of ALL project quick links PUT » a new collection of quick links (in request body)
Resource: Entrypoints (e.g. chromosomes)
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp}/db/{db}/ep/{ep}	GET » entrypoint PUT » a new entrypoint into database or new entrypoint name (in request body) for existing entrypoint
Resource: Annotation Tracks
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp}/db/{db}/trk/{trk}	GET » track PUT » a new track into database or new track name (in request body) for existing track
/REST/v1/grp/{grp}/db/{db}/trk/{trk}/url	GET » track URL PUT » a new track URL (in request body) DELETE » track URL
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/urlLabel	GET » track URL label text PUT » a new track URL label text(in request body) DELETE » track URL label text
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/description	GET » track description PUT » a new track description DELETE » track description
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/templateUrl	GET » track URL from template genome
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/templateUrlLabel	GET » track URL label text from template genome
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/templateDescription	GET » track description from template genome
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/classes	GET » collection of classes/categories
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/annoAttributes	GET » collection of user-defined annotation attributes/properties
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/style	GET » user-defined style for track PUT » a new style for track (in request body) DELETE » user-defined style for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/color	GET » user-defined color for track PUT » a new color for track (in request body) DELETE » user-defined color for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/display	GET » user-defined display for track PUT » a new display for track (in request body) DELETE » user-defined display for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/rank	GET » user-defined rank for track PUT » a new rank for track (in request body) DELETE » user-defined rank for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/defaultStyle	GET » default style for track PUT » a new default style for track (in request body) DELETE » default style for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/defaultColor	GET » default color for track PUT » a new default color for track (in request body) DELETE » default color for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/defaultDisplay	GET » default display for track PUT » a new default display for track (in request body) DELETE » default display for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/defaultRank	GET » default rank for track PUT » a new default rank for track (in request body) DELETE » default rank for track
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/links	GET » collection of links PUT » a new collection of links (in request body) DELETE » collection of links
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/templateLinks	GET » collection of links from template genome
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/bigBed	GET » the file PUT » start the process to create the file DELETE » the file
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/bigWig	GET » the file PUT » start the process to create the file DELETE » the file
Resource: Track Attributes
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attributes	GET » collection of user-defined track attributes
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attribute/{attribute}/value	GET » The value of a user-defined track attribute PUT » a new value for the track attribute (in request body) DELETE » the track attribute
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attribute/{attribute}/display	GET » The user-defined display settings for a track attribute PUT » New user-defined display settings for a track attribute DELETE » User-defined display settings for a track attribute (restores group default)
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attribute/{attribute}/defaultDisplay	GET » The group default display settings for a track attribute PUT » New group default display settings for a track attribute
Resource: Annotations
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/annos	GET » annotations in track, falling within landmark if any
/REST/v1/grp/{grp} /db/{db}/trks/annos	GET » annotations in tracks (in request body), falling within landmark if any
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/annos/count	GET » count of annotations in track, falling within landmark if any
/REST/v1/grp/{grp} /db/{db}/trks/annos/count	GET » count of annotations in tracks (in request body), falling within landmark if any
Resource: Layouts
Resource Path (rsrcPath)	Description
/REST/v1/grp/{grp} /db/{db}/annos/layouts	GET » a list of all of the saved tabular layouts for this database PUT » insert a new tabular layout into this database (in request body)
/REST/v1/grp/{grp} /db/{db}/annos/layout/{layout}	GET » a saved tabular layout definition PUT » insert a new tabular layout or update existing (in request body) DELETE » delete saved tabular layout
/REST/v1/grp/{grp} /db/{db}/annos/layout/{layout} /attribute/{attribute}	GET » a specific attribute about a saved tabular layout PUT » a new value for the attribute (userId, created, and modified are read-only)

We will differentiate between method return values, which all methods have, and resource representations, which methods that retrieve or send data representations need. Successful method calls, whether they retrieve or modify data, generally return some kind representation even if it's the result of creating or updating the resource; deletion generally does not return a representation.

The return value of a method indicates success or the type of failure encountered and can be found in the HTTP response code. Genboree uses a subset of the standard HTTP response codes, but whose definitions have high fidelity to those of the HTTP standard.

Success can be nuanced, but the most common success code is 200 ('OK'). Various types of failures are possible, and the HTTP code plus any information in the response body helps indicate what went wrong. Failures are either client-side errors or server-side errors.

SUCCESS CODES
HTTP Status Code	HTTP Status Text	Indication
200	OK	Request to obtain, alter, or delete resource succeeded.
201	Created	Created a new resource.
203	Accepted	Long-running resource alteration/creation/deletion accepted for processing.
301	Moved Permanently	Request to rename resource succeeded. Now has new resource URL.
CLIENT-SIDE ERROR CODES
HTTP Status Code	HTTP Status Text	Indication
400	Bad Request	Request could not be understood as made (URL escaped improperly?).
403	Forbidden	Bad authentication info or not authorized to perform method on resource.
404	Not Found	Resource specified by URL doesn't exist (URL escaped improperly?)
405	Method Not Allowed	Resource doesn't support the method [yet]; other methods are allowed.
409	Conflict	Creating/altering resource causes conflict with other existing resource(s). (e.g. resource name already taken)
415	Unsupported Media Type	Representation format parameter or representation itself from client is not valid for the resource.
501	Not implemented	No methods implemented [yet] for this resource.
SERVER-SIDE ERROR CODES
HTTP Status Code	HTTP Status Text	Indication
500	Internal Server Error	Unexpected server error encountered performing method on resource.