|
Storing and accessing binary data (BLOBs)
|
blob | Get information on a given blob. (administrative) |
blobs | Get information on given blobs. (administrative) |
chmod | Update an existing blob's sharing options. (administrative) |
consumer | Get consumer's storage usage statistics. (administrative) |
delete | Delete a blob (or multiple blobs). (administrative) |
get | Get the contents of a blob. |
inspect_blob | Inspect the blob's contents and retrieve basic metadata |
put | Put a blob into the database, using form-data encoding. (administrative) |
put_base64 | Put a blob into the database, using base64 encoding. (administrative) |
put_sha1 | Put a blob into the database, using a SHA-1 hash. (administrative) |
put_text | Put a text blob into the database. (administrative) |
put_unsigned | Upload data using form-data encoding. |
user | Get storage usage statistics for a given user. (administrative) |
users | Get storage usage statistics for given users. (administrative) |
users_all | Get storage usage statistics for all users. (administrative) |
services/blobbox/blob ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Get information on a given blob.
| ||||||
blob_id | required |
Blob ID. You may get information only on blobs which were uploaded by yourself (using your consumer key). All foreign blobs will appear as inexistent. If you want to get the content of the blob, use the get method. |
||||
fields | optional |
Default value: (all) Pipe-separated list of informational fields/sections you're interested in. This must be any subset of keys, which are described in the returns section. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary of selected fields and their values. Available fields:
If the blob does not exist (or you don't own it), you will get a HTTP 400 error. |
services/blobbox/blobs ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Get information on given blobs.
| ||||||
blob_ids | required |
Pipe-separated list of blob IDs (no more than 500). You may get information only on blobs which were uploaded by yourself (using your consumer key). All foreign blobs will appear as inexistent. If you want to get the content of the blob, use the get method. |
||||
fields | required | Pipe-separated list of informational fields/sections you're interested in. This must be any subset of keys, which are described in the returns section of the blob method. | ||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary. Blob IDs will be mapped to keys of this dictionary. Each value will be a dictionary of the same structure as described in the blob method. For all invalid references (blob IDs which point to inexistent blobs, or blobs you do not own), the value will be null (instead of a dictionary). |
services/blobbox/chmod ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Update an existing blob's sharing options.
| ||||||
blob_id | required | ID of the blob (you got it from the put_* method). It has to exist and you have to be its owner. | ||||
read_access | optional |
Default value: skip One of the options listed in the put_text method, or a special skip option to indicate that you don't want to change the previous settings. |
||||
min_age | optional |
Default value: skip One of the options listed in the put_text method, or a special skip option to indicate that you don't want to change the previous settings. Just to clear up: We will count this age starting from the current time (and not from the original upload time). |
||||
max_age | optional |
Default value: skip One of the options listed in the put_text method, or a special skip option to indicate that you don't want to change the previous settings. Just to clear up: We will count this age starting from the current time (and not from the original upload time). |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: Currently, this method always returns the same value: a dictionary with single success key with values of true. |
services/blobbox/consumer ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Get consumer's storage usage statistics.
| ||||||
fields | optional |
Default value: hard_count|hard_vsize Pipe-separated list of informational fields/sections you're interested in. This must be any subset of keys, which are described in the returns section. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary of selected fields and their values. Available fields:
vsize stands for virtual size - the sum of lengths of your blobs. The amount of physical storage which is actually used for your data may vary, depending on the underlying implementation and system settings. I.e. if you upload the same blob 100 times, each weighting 1 MB, you will get 100 blob_ids and your all_vsize will increase by 100 MB. However, internally the file will be stored only once. Similarly, we may also compress your blobs before storing, etc. |
services/blobbox/delete ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Delete a blob (or multiple blobs).
| ||||||
blob_ids | required | Pipe-separated list of blob IDs (no more than 500). You may only delete blobs which you have uploaded yourself. All other blob IDs will be ignored. | ||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary of the following structure:
|
services/blobbox/get ¶
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Get the contents of a blob.
| ||||||
blob_id | required | Blob ID. You may only read blobs which you have access to (see the read_access parameter in the put_text method). Unaccessible blobs will appear as inexistent. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: HTTP 200 response with raw contents of the blob. If the blob does not exist (or you do not have access to it), we will respond with a HTTP 400 error. |
services/blobbox/inspect_blob ¶
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can. Inspect the blob's contents and retrieve basic metadata. This method attempts to inspect the binary contents of the blob and extract some basic metadata (without the need for you to actually download the blob itself). Keep in mind however, that this method is kept primarilly for debugging purposes: it runs only the very simplest of tests, and the accuracy of these tests is not guaranteed. It is your responsibility to store (on your servers) detailed metadata on your blobs, if you really need such data. | ||||||
blob_id | required |
Blob ID. You can only inspect blobs which you have access to (see the read_access parameter in the put_text method). Unaccessible blobs will appear as inexistent. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional |
Required only if you've chosen jsonp as a return format. |
||||
Plus optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary of following fields and their values:
|
services/blobbox/put ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Put a blob into the database. Use form-data encoding to pass the binary data. Please note that we require SSL and OAuth PLAINTEXT signature for this method to work (regular OAuth 1.0 SHA1 signature doesn't work correctly with multipart/form-data encoding). Please include an Access Token if you have one (why?) | ||||||
data | required | The file to be uploaded. Your request has to use multipart/form-data encoding and the data key must have a "filename" in its Content-Disposition header. | ||||
read_access | optional |
Default value: consumer Same as in the put_text method. |
||||
min_age | optional |
Default value: none Same as in the put_text method. |
||||
max_age | optional |
Default value: none Same as in the put_text method. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization. | ||||||
Returned value: Same as in the put_text method. |
services/blobbox/put_base64 ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Put a blob into the database. Use base64 encoding to pass the binary data. Please include an Access Token if you have one (why?) | ||||||
data | required |
Base64-encoded data to be stored (no more than 1 MB). This method is not recommended. It is more efficient to use the put method (which also allows you to store bigger blobs than 1MB!). |
||||
read_access | optional |
Default value: consumer Same as in the put_text method. |
||||
min_age | optional |
Default value: none Same as in the put_text method. |
||||
max_age | optional |
Default value: none Same as in the put_text method. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization. | ||||||
Returned value: Same as in the put_text method. |
services/blobbox/put_sha1 ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Put a text blob into the database, using a SHA-1 hash. Usually you will use this method after you upload a file with put_unsigned. However, you may also attempt to use this method if you have a reason to suspect that your content may already exist (or it existed recently) in our blobbox database. USOS API will try to find the content and if it succeeds, it will be linked to a new blob ID. Please include an Access Token if you have one (why?) | ||||||
sha1 | required | SHA-1 hash of the data to be stored. | ||||
datasize | required | Length of the data, in bytes (for some extra security). | ||||
read_access | optional |
Default value: consumer Same as in the put_text method. |
||||
min_age | optional |
Default value: none Same as in the put_text method. |
||||
max_age | optional |
Default value: none Same as in the put_text method. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization. | ||||||
Returned value: Same as in the put_text method. |
services/blobbox/put_text ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Put a text blob into the database. Please include an Access Token if you have one (why?) | ||||||
data | required |
Data to be stored (no more than 1 MB). This method can be used for text blobs only. You'll get an error if you try to send binary data which cannot be read as utf8-encoded text. Use put or put_base64 methods if you're not sure if your content is binary or not. If 1 MB id not enough, use put or put_unsigned methods to upload your data. |
||||
read_access | optional |
Default value: consumer Sharing options. One of the following values:
Regardless of what you choose, only you (the Consumer) will be allowed to update or delete the data. You can use the sharing options to allow others to read your data, but you cannot allow others to change it in any way. |
||||
min_age | optional |
Default value: none By default (if min_age and max_age are set to none), your data is kept indefinitely (or, until explicit removal). When passing this parameter, you allow us to delete your data after the specified time. Integer, or a special none value. The minimum number of seconds to store the data (counting from now). We will not delete your data before this time, but we may choose to store it longer, based, for example, on its size and last access time (blobs which are regularly read may be kept much longer, even indefinitely). This parameter is useful when you want to allow public read access to a big chunk of temporary data (like an email attachment), but you're not sure how long it takes until people will actually stop accessing it. You may combine this parameter with max_age or expires. |
||||
max_age | optional |
Default value: none By default (if min_age and max_age are set to none), your data is kept indefinitely (or, until explicit removal). By passing this parameter, you tell us to delete it after a specified time. Integer, or a special none value. The maximum time (in seconds) after which the data must be deleted. Note, that the data may be deleted sooner, if you use min_age parameter. |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization. | ||||||
Returned value: A dictionary of the following structure:
In case of storage error (i.e. out of space), we will respond with HTTP 500 status and USOS API administrators will be notified. |
services/blobbox/put_unsigned ¶
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
This method does not put the blob into the database. It does however temporarily save the file and wait for you to complete the put operation. In order for such data to become a "fully qualified" blob, you need to call the put_sha1 method afterwards. This method does not require OAuth signatures, so you could use it to upload files directly from your user's browser. However you would also need to find a way to retrieve SHA1 of the uploaded file from your user's browser which is tricky... Probably it would be easier for you to simply store the file temporarily on your server, and then use the put to store it. Important: You have to call the put_sha1 method shortly after finishing the file upload. Otherwise, your file will be deleted. | ||||||
data | required | The file to be uploaded. Your request has to use multipart/form-data encoding and the data key must have a "filename" in its Content-Disposition header. | ||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
No additional OAuth arguments are required. If you provide any, they will be ignored. | ||||||
Returned value: Currently, this method always returns the same value: a dictionary with single success key with the value of true. |
services/blobbox/user ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Get storage usage statistics for a given user. Note, that user stats do not include blobs uploaded by other consumers! You have access only to stats related to your application. | ||||||
user_id | required | ID of the user. If you provide an invalid user ID, you will get a HTTP 400 error. | ||||
fields | optional |
Default value: hard_count|hard_vsize Pipe-separated list of fields (as in the consumer method). |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary of the same structure as the one returned in the consumer method. However, all the values will be computed against blobs uploaded by matched users only. |
services/blobbox/users ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
Get storage usage statistics grouped by users. Note, that user stats do not include blobs uploaded by other consumers! You have access only to stats related to your application. | ||||||
user_ids | required | Pipe-separated list of user IDs (no more than 500). | ||||
fields | optional |
Default value: hard_count|hard_vsize Pipe-separated list of fields (as in the consumer method). |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: A dictionary. User IDs will be mapped to keys of this dictionary. Each value will be a dictionary of the same structure as the one returned in the consumer method. However, all the values will be computed against blobs uploaded by matched users only. For all invalid references (unknown user IDs), the value will be null. |
services/blobbox/users_all ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
URLs of the methods are hidden, because this installation is
the mother server.
Click here for the list of all public USOS API installations. |
||||||
This method works like the users method, but it returns all users in whose name you store any data. Note, that the result might be very large. | ||||||
fields | optional |
Default value: hard_count|hard_vsize Pipe-separated list of fields (as in the consumer method). |
||||
format | optional |
Default value: json Format in which to return values. See supported output formats. |
||||
callback | optional | Required only if you've chosen jsonp as a return format. | ||||
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required. | ||||||
Returned value: Same as the the users method. Note: Only users with all_count greater than zero will be included. |