This document describes the HTTP API endpoints used by the CAS (Content Addressable Storage) client to interact with the remote CAS server.
To authenticate, authorize, and obtain the API base URL, follow the instructions in Authentication.
Sometimes hashes are used in API paths as hexadecimal strings (reconstruction, xorb upload, global dedupe API).
To convert a 32 hash to a 64 hexadecimal character string to be used as part of an API path there is a specific procedure, do not directly convert each byte.
For every 8 bytes in the hash (indices 0-7, 8-15, 16-23, 24-31) reverse the order of each byte in those regions then concatenate the regions back in order.
Otherwise stated, consider each 8 byte part of a hash as a little endian 64 bit unsigned integer, then concatenate the hexadecimal representation of the 4 numbers in order (each padded with 0's to 16 characters).
Suppose a hash value is:
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]
Then before converting to a string it will first have its bytes reordered to:
[7, 6, 5, 4, 3, 2, 1, 0, 15, 14, 13, 12, 11, 10, 9, 8, 23, 22, 21, 20, 19, 18, 17, 16, 31, 30, 29, 28, 27, 26, 25, 24]
So the string value of the the provided hash [0..32] is NOT 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f.
It is: 07060504030201000f0e0d0c0b0a0908171615141312111f1e1d1c1b1a1918.
/v1/reconstructions/{file_id}GETfile_id: File hash in hex format (64 lowercase hexadecimal characters).
See file hashes for computing the file hash and converting hashes to strings.Range: Optional. Format: bytes={start}-{end} (end is inclusive).readQueryReconstructionResponse)json
{
"offset_into_first_range": 0,
"terms": [...],
"fetch_info": {...}
}
400 Bad Request: Malformed file_id in the path. Fix the path before retrying.401 Unauthorized: Refresh the token to continue making requests, or provide a token in the Authorization header.404 Not Found: The file does not exist. Not retryable.416 Range Not Satisfiable: The requested byte range start exceeds the end of the file. Not retryable./v1/chunks/{prefix}/{hash}GETprefix: The only acceptable prefix for the Global Deduplication API is default-merkledb.hash: Chunk hash in hex format (64 lowercase hexadecimal characters).
See Chunk Hashes to compute the chunk hash and converting hashes to strings.readapplication/octet-stream), deserialize as a shard.400 Bad Request: Malformed hash in the path. Fix the path before retrying.401 Unauthorized: Refresh the token to continue making requests, or provide a token in the Authorization header.404 Not Found: Chunk not already tracked by global deduplication. Not retryable./v1/xorbs/{prefix}/{hash}POSTprefix: The only acceptable prefix for the Xorb upload API is default.hash: Xorb hash in hex format (64 lowercase hexadecimal characters).
See Xorb Hashes to compute the hash, and converting hashes to strings.writeapplication/octet-stream).
See xorb format serialization.UploadXorbResponse){
"was_inserted": true
}
Note: was_inserted is false if the Xorb already exists; this is not an error.
Error Responses: See Error Cases
400 Bad Request: Malformed hash in the path, Xorb hash does not match the body, or body is incorrectly serialized.401 Unauthorized: Refresh the token to continue making requests, or provide a token in the Authorization header.403 Forbidden: Token provided but does not have a wide enough scope (for example, a read token was provided). Retry with a write scope token./v1/shardsPOSTwriteapplication/octet-stream).
See Shard format guide.UploadShardResponse){
"result": 0
}
result is:0: The Shard already exists.1: SyncPerformed — the Shard was registered.The value of result is does not carry any meaning, if the upload shard API returns a 200 OK status code, the upload was successful and the files listed are considered uploaded.
400 Bad Request: Shard is incorrectly serialized or Shard contents failed verification.401 Unauthorized: Refresh the token to continue making requests, or provide a token in the Authorization header.403 Forbidden: Token provided but does not have a wide enough scope (for example, a read token was provided).Authorization header.read token was provided for an API requiring write scope).GET APIs where the resource (Xorb, file) does not exist.