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 command was successful
1	Empty	If a class or property key was not present but used for searching.
2	Exists	A conditional add found a unique instance of an existent object.
3	NotUnique	A search query specified "unique" = true but got multiple results.
4	Response size is too large	A query is attempting to retrieve binary data larger than allowed (default is 256MB).
-1	Error	There was an error, the "info" field should provide a message.

If every command within a transaction succeeded, ApertureDB will return one JSON object with the corresponding status code and results. If any of the commands fails, ApertureDB 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" ]
            }
    }
}

# If a Find*, let's say a FindEntity finds no matching object,
# the response is as shown here

"FindEntity" : {
    "status": 0,
    "returned": 0
}

# For Find* commands that return blobs, if "blobs" were set to
# "false" and no objects matched, the response will be similar to
# the one above. The array size of blobs array will be 0.
# In case where "blobs" is "true" and we found objects matching
# given constraints but no properties were requested, let's say
# for a "FindImage" where 4 images matched, response is as shown here.
# The array size of blobs array will be 4 with first blob at index 0

"FindImage" : {
    "status": 0,
    "returned": 4,
    "blobs_start": 0
}

# If "count" was set to "true" in the "results" block or "sum" / "average"
# were requested in the "FindImage" example above, the response is
# as shown here

"FindImage": {
    "status": 0,
    "count": 4,
    "returned": 4,
    "blobs_start": 0
}