Responses

In regular responses, the JSON response is an array of objects where each member gives information about how a particular command executed. Any time there is an error, the JSON response returned will not be an array but a JSON object with a member “status”. So a check to see whether status is a member of response should reveal whether there was an error or not.

Responses for all the Find* commands indicate if “blob” was set to true or false when requesting results. If “blob” is true, there is an additional variable “blob_start” which gives the 0-based vector index for where the first blob corresponding to that command is placed in the return vector. In case of FindEntity, even if “blob” is true, not all entities have a blob associated with them. Therefore, “_blob” (_ is to avoid clashing with potentially a property within entity named blob) being true or false is embedded along with the property values list.

Return Status

Each call returns a “status” with an integer value listed with its meaning in the table below. In case a command is unsuccessful, we return an error code and provide information on why it failed using the “info” field.

However, if there is a local id provided in such a call, we treat it as an exception which causes the rest of the transaction to abort. This is necessary to avoid relying on calls that were not successful. When a transaction aborts, it undoes all the metadata changes that were made until the point where the error occurred.

Return Value Status Description
0 Success The call was successful and performed what was expected of it
1 Empty A search query returned no results.
2 Exists A conditional add found a unique instance of the entity to exist already. If not unique, an error(-1) is returned depending on absence/presence of _ref in the call.
3 NotUnique If a search query wanted a unique entity but got multiple results. An error(-1) is returned depending on absence/presence of _ref in the call.
-1 Error There was an error and the error message indicates what

If every command within a transaction succeeded, ApertureData Platform will return one JSON object with the corresponding status code and possible results information. If any of the commands fails, ApertureData Platform will return a single JSON object indicating the error status, information about what caused the failure, and the command that caused the failure.

Examples

# Successful AddEntity

"AddEntity" : {
    "status": 0
}

# FindEntity with using a wrong "ref"

"FindEntity" : {
    "status": -1,
    "info": "Reference does not exist",
    "FailedCommand": {
        "FindEntity": {
            "_ref": 344554,
            "class": "patient",
            "constraints" : {
                "bcr_patient_barc": [ "==", "TCGA-02-0070" ]
            }
    }
}