HELP TOPIC: "8.C REST API – Representations"

Genboree resource state is communicated via representations which are text-based formats describing the data.

By default, representations are expressed as JSON data structures. JSON is a straight-forward, cheap to generate and parse, non-verbose syntax that is excellent for communicating simple data structures. Furthermore, its syntax is similar to that of many modern programming languages and should look familiar to most developers. Also, as valid Javascript code, it is suitable for Ajax use.

Individual resources are typically expressed as JSON hashes (a.k.a. JSON objects), whose keys/properties are named fields appropriate for the specific resource.

Collections of resources are expressed as JSON arrays (lists) of individual resources.

Support for other syntaxes is also present, to some degree. YAML, for example, which has many of the aforementioned advantages, is fully supported by the API and can be used instead of JSON. XML equivalent syntax is less robust and more verbose, but is supported for resource retrieval. Finally, some resources can be or must be expressed as enhanced LFF, the native Genboree format for genome annotations and entrypoints. Requesting a non-default syntax is done via the optional format parameter.

Currently, this help document will focus on the more important issue of the resource data structures, using the default syntax (JSON).

The table below indicates the representations for currently exposed resources. New resources will be added over time; if you wish to request a particular syntax or data structure representation for resources of interest, please contact us.

The representation types in the table encode both a data structure and the supported syntaxes. These types will be encountered in the reference links (in the refs key) to indicate the type of link, and in node names for XML.

The representation types are clickable links to a detailed description in the next section.

Resource: Users
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/usr/{usr}	GET	out » UsrPartial_JSON.YAML.XML or out » UsrDetailed_JSON.YAML.XML
/REST/v1/usr/{usr}/grps	GET » [ params: detailed ]	out » TxtList_JSON.YAML.XML or out » GrpDetailedList_JSON.YAML.XML
/REST/v1/usr/{usr}/grp/{grp}	GET	out » GrpDetailed_JSON.YAML.XML
Resource: User Groups
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp}	GET	out » GrpDetailed_JSON.YAML.XML
	PUT » new name (create or rename)	in » GrpDetailed_JSON.YAML.XML out » GrpDetailed_JSON.YAML.XML
/REST/v1/grp/{grp}/dbs	GET	out » TxtList_JSON.YAML.XML
/REST/v1/grp/{grp}/prjs	GET	out » TxtList_JSON.YAML.XML
	PUT » new project (name in body)	in » Txt_JSON.YAML.XML out » Txt_JSON.YAML.XML
/REST/v1/grp/{grp}/usrs	GET » [ params: detailed ]	out » TxtList_JSON.YAML.XML or out » UsrPartialList_JSON.YAML.XML
	PUT » existing user(s) in group as subscriber (name in body)	in » TxtList_JSON.YAML.XML out » TxtList_JSON.YAML.XML
/REST/v1/grp/{grp}/usr/{usr}	GET	out » UsrPartial_JSON.YAML.XML or out » UsrDetailed_JSON.YAML.XML
	PUT » existing user in group as subscriber	out » UsrPartial_JSON.YAML.XML or out » UsrDetailed_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp}/usr/{usr}/role	GET	out » Role_JSON.YAML.XML
	PUT » existing user in group (role in body)	in » Role_JSON.YAML.XML out » Role_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /unlockedResources	GET	out » unlockedRefEntityList_JSON.YAML.XML
	PUT » set of resources	in » unlockedRefEntityList_JSON.YAML.XML
	DELETE » set of resources	in » unlockedRefEntityList_JSON.YAML.XML
Resource: User Databases
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp}/db/{db}	GET	out » DbDetailed_JSON.YAML.XML
	PUT » new database [ params: templateName ]	in » DbDetailed_JSON.YAML.XML out » DbDetailed_JSON.YAML.XML
/REST/v1/grp/{grp}/db/{db}/eps	GET	out » EpDetailedList_JSON.YAML.XML or out » EpList_LFF
	PUT » new entrypoints	in » EpDetailedList_JSON.YAML.XML or  in » EpList_LFF
/REST/v1/grp/{grp}/db/{db}/trks	GET » [ params: detailed ]	out » TxtList_JSON.YAML.XML or out » TrkDetailedList_JSON.YAML.XML
/REST/v1/grp/{grp}/db/{db}/seq	GET	out » FASTA
Resource: User Projects
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp}/prj/{prj}	GET	out » Txt_JSON.YAML.XML
	PUT » new name; i.e. create, rename or copy	in » Txt_JSON.YAML.XML or  in » Ref_JSON.YAML.XML (ref to another project for copy) out » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /prj/{prj}/title	GET	out » Txt_JSON.YAML.XML
	PUT » new title	in » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /prj/{prj}/description	GET	out » Txt_JSON.YAML.XML
	PUT » new description	in » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /prj/{prj}/customContent	GET	out » Txt_JSON.YAML.XML
	PUT » new content	in » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /prj/{prj}/news	GET	out » PrjNewsList_JSON.YAML.XML
	PUT » new news list	in » PrjNewsList_JSON.YAML.XML
/REST/v1/grp/{grp} /prj/{prj}/links	GET	out » PrjLinkList_JSON.YAML.XML
	PUT » new links list	in » PrjLinkList_JSON.YAML.XML
/REST/v1/grp/{grp} /prj/{prj}/quickLinks	GET	out » PrjQLinkList_JSON.YAML.XML
	PUT » new quick links list	in » PrjQLinkList_JSON.YAML.XML
Resource: Entrypoints (e.g. chromosomes)
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp} /db/{db}/ep/{ep}	GET	out » EpDetailed_JSON.YAML.XML or out » EpList_LFF
	PUT » add new entrypoints	in » EpDetailed_JSON.YAML.XML or  in » EpList_LFF
	DELETE
Resource: Annotation Tracks
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp} /db/{db}/trk/{trk}	GET » [ params: detailed ]	out » Txt_JSON.YAML.XML or out » TrkDetailed_JSON.YAML.XML
	PUT » new name; i.e. create or rename	in » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /url	GET	out » Txt_JSON.YAML.XML
	PUT » new URL	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /urlLabel	GET	out » Txt_JSON.YAML.XML
	PUT » new URL Label	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /description	GET	out » Txt_JSON.YAML.XML
	PUT » new description	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /templateUrl	GET	out » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /templateUrlLabel	GET	out » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /templateDescription	GET	out » Txt_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /style	GET	out » Txt_JSON.YAML.XML
	PUT » new user defined style	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /defaultStyle	GET	out » Txt_JSON.YAML.XML
	PUT » new group default style	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /color	GET	out » Txt_JSON.YAML.XML
	PUT » new user defined color	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /defaultColor	GET	out » Txt_JSON.YAML.XML
	PUT » new group default color	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /display	GET	out » Txt_JSON.YAML.XML
	PUT » new user defined display	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /defaultDisplay	GET	out » Txt_JSON.YAML.XML
	PUT » new group default display	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /rank	GET	out » Txt_JSON.YAML.XML
	PUT » new user defined sort order	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /defaultRank	GET	out » Txt_JSON.YAML.XML
	PUT » new group default sort order	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /classes	GET	out » TxtList_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /annoAttributes	GET	out » TxtList_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /links	GET	out » TrkLinkList_JSON.YAML.XML
	PUT » set of links	in » TrkLinkList_JSON.YAML.XML or  in » Ref_JSON.YAML.XML (containing ref to templateLinks)
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /templateLinks	GET	out » TrkLinkList_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /bigBed	GET	out » bigbed file (binary)
	PUT	initiates process to create bigbed file
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /bigWig	GET	out » bigwig file (binary)
	PUT	initiates process to create bigwig file
	DELETE
Resource: Track Attributes
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /attributes	GET	out » TxtList_JSON.YAML.XML or out » TrkAttrDetailedList_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attribute/{attribute}/value	GET	out » Txt_JSON.YAML.XML
	PUT » new value	in » Txt_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attribute/{attribute}/display	GET	out » AttrDisplay_JSON.YAML.XML
	PUT » new user defined display settings	in » AttrDisplay_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/trk/{trk}/attribute/{attribute}/defaultDisplay	GET	out » AttrDisplay_JSON.YAML.XML
	PUT » new group default display settings	in » AttrDisplay_JSON.YAML.XML
Resource: Annotations
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /annos	GET » [ params: landmark, layoutName ]	in » Layout_JSON.YAML.XML       (only when format=layout) out » AnnoList_LFF.LAYOUT
/REST/v1/grp/{grp} /db/{db}/trks /annos	GET » annos in tracks [ params: landmark, layoutName ]	in » TxtList_JSON.YAML.XML       List of Track names out » AnnoList_LFF.LAYOUT
/REST/v1/grp/{grp} /db/{db}/trk/{trk} /annos/count	GET » [ params: landmark ]	out » Count_JSON.YAML.XML
/REST/v1/grp/{grp} /db/{db}/trks /annos/count	GET » count annos in tracks [ params: landmark ]	in » TxtList_JSON.YAML.XML out » Count_JSON.YAML.XML
Resource: Tabular Layouts
Resource Path (rsrcPath)	Method Type	Representation Type (repType)
/REST/v1/grp/{grp} /db/{db}/annos /layout/{layout}	GET	out » Layout_JSON.YAML.XML
	PUT » insert / update layout	in » Layout_JSON.YAML.XML
	DELETE
/REST/v1/grp/{grp} /db/{db}/annos /layout/{layout} /attribute/{attribute}	GET	out » Txt_JSON.YAML.XML
	PUT » change layout attribute	in » Txt.YAML.XML
/REST/v1/grp/{grp} /db/{db}/annos /layouts	GET	out » LayoutList_JSON.YAML.XML
	PUT » insert layout	in » Layout_JSON.YAML.XML

Most Genboree resources have data structure-based representations that can be formated using JSON syntax, YAML syntax, and in some cases XML syntax. A minority have specific formats that are more appropriate, such as LFF for annotations and FASTA for DNA sequence.

The current representations listed below are expressed in the default JSON syntax.

All data structure representations are wrapped in a simple envelope that provides status information under the status key and the data structure itself under the data key.

 Common Envelope:

{
  "data" => <jsonRepresentation>,     # One of the data strcutures below
  "status" =>
  {
    "statusCode" => "<value>",        # Status code as -text-.
    "msg" => "<value>"                # Status msg. Useful if something went wrong.
  }
}

• - The non-data structure representations (LFF, FASTA, etc) are NOT wrapped in the common envelope.
• - The value for the data key can null if there is an error.
• - When sending data to the server, the status key will be ignored (it can be omitted).

These data structures correspond to specific representations referred to in the table above. The data structure goes in place of the jsonRepresentation place-holder in the Common Envelope above.

 Count: ( repType » Count_JSON.YAML.XML )

{
  "count" : <value>                # The count (an integer)
}

 Text: ( repType » Txt_JSON.YAML.XML )

{
  "text" : "<value>",              # The text value.
  "refs" :                         # Link(s) to more info, if available, keyed by repType.
  {
    "<repType>" : "<coreURI>"
  }
}

 Text List: ( repType » TxtList_JSON.YAML.XML )

[                                  # List of Txt objects.
  {
    "text" : "<value>",            # The text value
    "refs" :                       # Link(s) to more info, if available, keyed by repType.
    {
      "<repType>" : "<coreURI>"
    }
  },
  ...
]

 Ref: ( repType » Ref_JSON.YAML.XML )

{
  "url" : <value>                # The reference URL to an API resource
}

 Unlocked Ref List: ( repType » UnlockedRefList_JSON.YAML.XML )

[                                  # List of Txt objects.	
  {
    "url" : <value>                # The reference URL to an API resource
    "key" : <value>                # The unlock key for the API resource
  },
  ...
]

 User [Detailed]: ( repType » UsrDetailed_JSON.YAML.XML )

{
  "login" : "<login>",
  "firstName" : "<firstName>",
  "lastName" : "<lastName>",
  "institution" : "<institution>",
  "telephone" : "<telephone>",
  "email" : "<email>",
  "refs" : { }
}

 User [Detailed] List: ( repType » UsrDetailedList_JSON.YAML.XML )

[
  {
    "login" : "<login>",
    "firstName" : "<firstName>",
    "lastName" : "<lastName>",
    "institution" : "<institution>",
    "telephone" : "<telephone>",
    "email" : "<email>",
    "refs" : { }
  },
  ...
]

 User [Partial]: ( repType » UsrPartial_JSON.YAML.XML )

{
  "login" : "<login>",
  "firstName" : "<firstName>",
  "lastName" : "<lastName>",
  "institution" : "<institution>",
  "email" : "<email>",
  "refs" : { }
}

 User [Partial] List: ( repType » UsrPartialList_JSON.YAML.XML )

[
  {
    "login" : "<login>",
    "firstName" : "<firstName>",
    "lastName" : "<lastName>",
    "institution" : "<institution>",
    "email" : "<email>",
    "refs" : { }
  },
  ...
]

 Group [Detailed]: ( repType » GrpDetailed_JSON.YAML.XML )

{
  "name" : "<groupName>",
  "description" : "<description>",
  "refs" : { }
}

 Group [Detailed] List: ( repType » GrpDetailedList_JSON.YAML.XML )

[
  {
    "name" : "<groupName>",
    "description" : "<description>",
    "refs" : { }
  },
  ...
]

 Role: ( repType » Role_JSON.YAML.XML )

{
  "role" : "<roleName>",               # Must be: subscriber, author or administrator
  "permissionBits" : "<value>",        # currently unimplemented
  "refs" : { }
}

 Database [Detailed]: ( repType » DbDetailed_JSON.YAML.XML )

{
  "name" : "<databaseName>",
  "refSeqId" : "<refSeqId>",           # refSeqId is a unique id. For use in composing browser URLs, etc.
  "species" : "<species>",
  "version" : "<version>",
  "description" : "<description>",
  "entrypoints" :
  {
    "count" : "<value>",               # Count of ALL the entrypoints
    "entrypoints" :                    # List of EpDetailed objects.
    [                                  # - can be a -partial- list if there are lots (>100)
      {
        "name" : "<value>",
        "length" : "<value>" ,
        "refs" :                       # Link(s) to more info, if available, keyed by repType.
        {
          "EpDetailed_JSON.YAML.XML" : "<coreURI>"   # Link to the entrypoint resource itself.
        }
      },
      ...
    ]
  },
  "refs" : { }
}

 Entrypoint/Chromosome [Detailed]: ( repType » EpDetailed_JSON.YAML.XML )

{
  "name" : "<value>",
  "length" : "<value>" ,
  "refs" : { }
}

 Entrypoint/Chromosome [Detailed] List: ( repType » DbDetailedList_JSON.YAML.XML )

{
  "count" : "<value>",                 # Count of ALL the entrypoints
  "entrypoints" :                      # List of EpDetailed objects.
  [                                    # - can be a -partial- list if there are lots (>100)
    {
      "name" : "<value>",
      "length" : "<value>" ,
      "refs" :                         # Link(s) to more info, if available, keyed by repType.
      {
        "EpDetailed_JSON.YAML.XML" : "<coreURI>"      # Link to the entrypoint resource itself.
    }
   ...
  ]
}

 Track [Detailed]: ( repType » TrkDetailed_JSON.YAML.XML )

{
  "name" : "<typeA>:<subtypeB>",
  "description" : "<value>",
  "url" : "<value>",
  "urlLabel" : "<value>",
  "annoAttributes" :                      # List of attribute names associated with track (if any)
  [                                   # . list of Txt objects
    {
      "text" : "<value>",
      "refs" : { }
    },
  ...
  ],
  "refs" : { }
}

 Track [Detailed] List: ( repType » TrkDetailedList_JSON.YAML.XML )

[
  {
    "name" : "<typeA>":"<subtypeB>",
    "description" : "<value>",
    "url" : "<value>",
    "urlLabel" : "<value>",
    "classes" :                      # List of classes (categories) associated with track (if any)
    [                                # . list of Txt objects
      {
        "text" : "<value>",
        "refs" : { }
      },
      ...
    ],
    "annoAttributes" :                   # List of attribute names associated with track (if any)
    [                                # . list of Txt objects
      {
        "text" : "<value>"
        "refs" : { }
      },
      ...
    ],
    "refs" :
    {
      "TrkDetailed_JSON.YAML.XML" : "<coreURI>"      # Link to the track resource itself.
    }
  },
  ...
]

 Track Link: ( repType » TrkLink_JSON.YAML.XML )

{
  "url" : "<value>",
  "linkText" : "<value>",
  "refs" : { }
}

 Track Link List: ( repType » TrkLinkList_JSON.YAML.XML )

[
  {
    "url" : "<value>",
    "linkText" : "<value>",
    "refs" : { }
  },
  ...
]

 Attribute Display: ( repType » AttrDisplay_JSON.YAML.XML )

{
  "color" : "<value>",
  "rank" : "<value>",
  "flags" : "<value>",
  "refs" : { }
}

 Track Attribute [Detailed]: ( repType » TrkAttrDetailed_JSON.YAML.XML )

{
  "name" : "<value>",
  "value" : "<value>",
  "display" :
  {
    "color" : "<value>",
    "rank" : "<value>",
    "flags" : "<value>",
    "refs" : { }
  }
  "defaultDisplay" :
  {
    "color" : "<value>",
    "rank" : "<value>",
    "flags" : "<value>",
    "refs" : { }
  }
  "refs" : { }
}

 Track Attribute [Detailed] List: ( repType » TrkAttrDetailedList_JSON.YAML.XML )

[
  {
    "name" : "<value>",
    "value" : "<value>",
    "display" :
    {
      "color" : "<value>",
      "rank" : "<value>",
      "flags" : "<value>",
      "refs" : { }
    }
    "defaultDisplay" :
    {
      "color" : "<value>",
      "rank" : "<value>",
      "flags" : "<value>",
      "refs" : { }
    }
    "refs" : { }
  },
  ...
]

 Project News List: ( repType » PrjNewsList_JSON.YAML.XML )

[                                   # List of ALL PrjNews items
  {                                 # . items not individually exposed (yet)
    "date" : "<date>",              # -> format: YYYY/MM/DD only (same day items sorted by texts)
    "updateText" : "<value>",       # -> could prefix with A,B,C or 1,2,3 to order same day items
    "refs" : { }
  },
  ...
]

 Project Link List: ( repType » PrjLinkList_JSON.YAML.XML )

[                                       # List of ALL PrjLink items
  {                                     # . items not individually exposed (yet)
    "url" : "<url>",
    "linkDesc" : "<value>",
    "linkText" : "<value>",
    "refs" : { }
  },
  ...
]

 Project Quick Links List: ( repType » PrjQLinkList_JSON.YAML.XML )

[                                      # List of ALL PrjQLink items
  {                                    # . items not individually exposed (yet)
    "url" : "<url>",
    "linkText" : "<value>",
    "refs" : { }
  },
  ...
]

 User [Detailed]: ( repType » UsrDetailed_JSON.YAML.XML )

{
  "login" : "<value>",
  "firstName" : "<value>",
  "lastName" : "<value>",
  "institution" : "<value>",
  "telephone" : "<value>",
  "email" : "<value>",
  "refs" : { }
}

 Tabular Layout: ( repType » Layout.YAML.XML )

{
  "name" : "<value>",              # The name of this layout.
  "description" : "<value>",       # The description of this layout.
  "userId" : "<value>",            # The ID of the user who created this layout.
  "created" : "<date>",            # The date on which this layout was created.
  "modified" : "<datetime>",       # The date / time this layout was last modified.
  "columns" : "<value>",           # A CSV list of the attributes in the order they are displayed.
                                   # The attribute names are prepended with either an 'l' or an 'a'
                                   # depending on their type.  'l' = LFF standard attribute,
                                   # 'a' = user-defined attribute.
  "sort" : "<value>",              # A CSV list of the attributes used in the sort order, encoded
                                   # the same as the "columns" field
  "groupMode" : "<value>",         # Either "terse", "verbose", or an empty string for ungrouped mode.
  "refs" :                         # Link(s) to more info, if available, keyed by repType.
  {
    "<repType>" : "<coreURI>"
  }
}

 Tabular Layout List: ( repType » LayoutList_JSON.YAML.XML )

[                                  # List of Layout objects.
  Layout,
  ...
]

 LFF Annotations List: ( repType » AnnoList_LFF.LAYOUT )

This corresponds to the [ annotations ] section in the DAS LFF format specification. See the detailed description of Genboree's enhanced LFF format for annotations, or the a user defined Tabular Layout (format=layout). Tabular Layouts are stored in the user databases or can be specified using HTTP request payloads.

 LFF Entrypoint/Chromosome List: ( repType » LffEpList )
This corresponds to the so-called [ entrypoints ] (a.k.a. [ references ]) section in the DAS LFF format specification. It is 3 tab-delimited fields: the chromosome/scaffold name, the type of entrypoing (recommendation: always use "Chromsome"), and the length in base pairs.

# EntrypointName  EntrypointType  EntrypointLength
chr1        Chromosome      247249719
chr2        Chromosome      242951149
chr20       Chromosome      62435964

 FASTA: ( repType » FASTA )
DNA sequence, in FASTA format.