|
Sharing files
|
create_link | Publish a file using an existing blob. (administrative) |
parse_link | Parse a link into blob_id and params. |
set_404 | Register/Unregister a custom 404 error handler. (administrative) |
services/fileshare/create_link ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
https://www.usosapi.amuz.bydgoszcz.pl/services/fileshare/create_link | ||||||
Publish a file using an existing blob for its contents. If you haven't uploaded the contents of your file yet, you must do so using the services/blobbox/put method. This method will provide with a special, publicly accessible URL which you can pass on to your users. Important: You should not assume, that the link will be a direct link to the file. We may choose to display some additional screens (e.g. a security warning) before we allow the user to view the file. As such, the URL is not meant to be used in some contexts, i.e. HTML <img src=""> elements. | ||||||
blob_id | required |
ID of the blob which holds the contents of your file. It must exist and you must be the owner of this blob. It should be saved with public read access rights (if it isn't, you will still get the link, but users won't be able to download the file). When blob expires, users will be redirected to your custom 404 page (see the set_404 method for details). |
||||
filename | required |
Blobs don't have names. How do you want to name your file? You don't need to get rid of spaces and/or special national characters. Most browsers can handle them properly (they get them replaced with characters compatible with their OS). However, you should make sure that your filename:
USOS API will take care of the rest of difficult cases (if it doesn't, contact the developers). Note, that during the process, your filename may get changed (invalid characters replaced, etc.). |
||||
content_type | optional |
If you know the right content type of the file, you may pass it here. Note, that many browsers guess content type correctly, based on the file extension (USOS API also may attempt to guess). |
||||
prefer_save | optional |
Default value: false By default, user's browser selects appropriate action based on file extension (and/or content type). Usually leaving this decision for the browser is the best you can do. However, if you really think the user should save the file (as opposed to viewing it), then set this parameter to true. Note, that this is only a hint. In the future, we may ignore this parameter completely or we may let the users choose the action for themselves. |
||||
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/fileshare/parse_link ¶
|
||||||
https://www.usosapi.amuz.bydgoszcz.pl/services/fileshare/parse_link | ||||||
Parse a link back into blob_id and params. Links produced by the create_link method are short, because their parameters are encoded and/or stored inside the USOS API database. Every link produced by the create_link method may be parsed back, producing the initial parameters (the ones which were supplied when calling the create_link method). Underlying blob may have been deleted, but these parameters are still present. Note, that usually you won't have any need to use this method. The standard course of action is, you simply give the link to your users. If you want to reference your data later, you may simply do that using the blob_id. | ||||||
link | required |
The link you got from the create_link method. It doesn't have to be a link produced by yourself. (Note, that you don't need a consumer key to use this 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. | ||||
No additional OAuth arguments are required. If you provide any, they will be ignored. | ||||||
Returned value: If the link is valid, you will receive a dictionary of the following structure:
If the link is invalid, you will get a HTTP 400 error. This means that the link was not created by this USOS API installation. |
services/fileshare/set_404 ¶
Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.
|
||||||
https://www.usosapi.amuz.bydgoszcz.pl/services/fileshare/set_404 | ||||||
When your blob expires, users won't be able to download the file. By default, USOS API will present them with a generic HTTP 404 error page. You should provide your users with more than that. We allow you to define a personalized "Not Found" error page, where you can introduce alternative ways of obtaining the file, if any exist (e.g. you may encourage them to contact the user which originally uploaded the file). | ||||||
url | required |
URL of your custom HTTP 404 page, or "none" if you don't want to use one. In case of error, users will be redirected there. We MAY append some extra parameters to your URL, to make it easier for you to recover from the error:
Important: All of these extra parameters are optional. We will try to pass all of them, but we may even end up appending none of them. You should be prepared for any configuration. |
||||
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. |