Object Details

All object types can store additional data in a "details" field using JSON format. The top level element must be an object or an array. Unlike properties, values stored in JSON aren't limited to strings and won't be included in search queries over objects (except for links). The details field commonly stores data necessary for an object to conform to a specific type or convention. You can store any arbitrary JSON except for specific reserved terms. You can use the getDetails call to access an object's details content.

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, which is defined as a JSON object or array per RFC4627. This 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)