Object Details

For all types of objects, additional data can be stored in a "details" field using the JSON format. RFC4627 describes what constitutes valid JSON -- for example, the top level element needs to be an object (hash) or an array. Unlike properties, the values stored in the JSON need not be strings, nor will they be examined in any search queries over the objects (with the exception of links which will be discussed shortly). In particular, the details will often store the necessary data to be conformant to a particular type, or convention. Arbitrary JSON can be stored with the exception of reserved strings mentioned below. The contents of an object’s details can be returned via a "getDetails" call.

Linking

A particularly useful feature of the details of an object is that a value in the JSON can be a "link" which contains information to refer to another object. For example, a file can contain a hash with the key "index" with the corresponding value set to a link pointing to the index file for that file. The syntax for such a link is a hash with a single key-value pair

{"$dnanexus_link": "<class>-<xxxx>"}

Note that if a project contains the file but not the index file, this link is not particularly helpful. However, if the index file object were to be later cloned into the same project, the link would become valid. These links can also be used to reference genomes that are available in public data sets.

The outgoing links of an object can be queried directly using a "describe" call on the object, and the incoming links can be queried using the /system/findDataObjects method.

API method: /class-xxxx/setDetails

Specification

Re-sets the content of the object’s details.

Inputs

• Any conformant JSON (i.e. a JSON object or array, per RFC4627), which will be the new content.

Outputs

• id string ID of the manipulated object

Errors

• ResourceNotFound (the specified object in the URL does not exist)

• InvalidInput (the string "$dnanexus_link" was found as a key but is not the single key in a hash or has a value which is not a string)

• PermissionDenied (UPLOAD access required for the project in which the object was created)

• InvalidState (the object is not in the "open" state)

API method: /class-xxxx/getDetails

Specification

Retrieves the content of the object’s details.

Inputs

• project string (optional) ID of a project that the getDetails call will be scoped to. If the object cannot be found in that project a ResourceNotFound error will be returned.

Outputs

• The contents of the object’s details

Errors

• ResourceNotFound (the specified object in the URL does not exist)

• PermissionDenied (VIEW access required)