Sharing files
:: services/fileshare module

This module is built on top of the blobbox module. So, if you want to use fileshare methods, you will probably need to dig into the blobbox module too.

It allows you to share a file publicly with end-users. Once you upload the file, we provide you with a public link. You will pass it on to your users and they will be able to download your file. The file will be available until explicit removal, or until it expires (we provide you with a couple of basic expiry options). We also let you customize what happens if the user tries to download an expired file.

You may share files as yourself (the Consumer) or as one of your users. (If the file originates from a user, you should always upload a user-reference along with it.)

Methods

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)

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapps.uni.opole.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:

  • does not begin with a dot,
  • does not exceed 255 characters in length.

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:

  • link - an URL which you should pass on to your users in order for them to download the file.

    As said before, you should not assume that the link will be a direct link to the file. Also note, that the link will expire along with its blob.
Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.uni.opole.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:

  • consumer_key - ID of the consumer which have uploaded the blob and produced the link,
  • user_id - user ID, in whose name the blob was uploaded (may be null),
  • blob_id - blob ID (the blob itself doesn't have to exist anymore),
  • filename - value given in the create_link's filename parameter (possible with some minor compatibility changes),
  • prefer_save - boolean, value given in the create_link's prefer_save parameter,
  • content_type - value given in the create_link's content_type parameter (may be null),
  • date_blob_created - datetime string, represents the date when the underlying blob was created.

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.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapps.uni.opole.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:

  • usosapi_consumer_key - your Consumer Key (useful if you want to register one 404 page for multiple Consumer Keys),
  • usosapi_blob_id - ID of the blob which the user was trying to access (and which got deleted),
  • usosapi_user_id - ID of the user who uploaded the blob (present only for blobs which were uploaded by a user),
  • usosapi_filename - filename which was used for serving the file (may differ from the one you've originally provided),
  • usosapi_date_blob_created - datetime string, represents the date when the blob was initially uploaded. Users may attempt to use old links years after blobs are deleted!

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.
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)