Photos
:: services/photos module

This module allows you to upload new user photos, and access their current visibility settings. (Downloading photos via this module has been deprecated.)

  • Most of these methods are BETA. They will probably stay this way for a long time. There's a huge chance they won't be backward-compatible in the future (especially those which expose the visibility permissions model).
  • Those methods which are not BETA, will of course stay backward compatible (e.g. the my_photo_visibility method).
  • If you're looking for a backward-compatible way of accessing user photos, then you should have a look at the photo_urls field in the services/users/user method.

Methods

can_see_photo BETA Check if one user can view other user's photo.
delete_photo BETA Delete user's photo. (administrative)
my_photo_visibility Get information on the visibility of the user's photo.
photo BETA Get user's photo.
settings BETA Get current photo settings. (administrative)
update_photo BETA Update user's photo. (administrative)

services/photos/can_see_photo

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.uni.opole.pl/services/photos/can_see_photo

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.

Check if the user's photo can be displayed.

More precisely, this method checks if the photo of the user with given user_id exists and the requester has sufficient permissions to view this photo. The "requester" can be both a user (if you provide an Access Token) or the Consumer (if you don't provide the Access Token). This method can be even called anonymously! (Some of the users agree to share their photo publicly with anyone.)

If you use the Access Token, then you probably should also acquire the photo scope from the user. You might be able to see more photos this way.

Please note, that - in most cases - there is no clear way for you to distinguish between situations when (a) you cannot view the photo, and (b) when the photo does not exist.
user_id optional

Default value: (access token issuer)

ID of a user.
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. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of following fields and their values:

  • can_see_photo - a boolean, true if and only if photo of user with given ID exists and requester has access to display this photo;

  • errors - a list of dictionaries. Empty list will be returned if can_see_photo equals to true.

    Each dictionary has following structure:
    • error - a name of error. At this moment two kinds of errors may appear.

      Possible values: object_forbidden, photo_not_found.

      It is guaranteed that an error object_forbidden will be placed at the beginning of errors list only if this error is raised.
    • message - a description of error.

Thrown errors:

  • object_not_found - user could not be found; param_name is equal to user_id.

services/photos/delete_photo

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

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
https://usosapps.uni.opole.pl/services/photos/delete_photo

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.

Delete user's photo.
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 required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_not_found - user could not be found; param_name is equal to user_id.

services/photos/my_photo_visibility

Consumer: required Token: required Scopes: photo SSL: not required
https://usosapps.uni.opole.pl/services/photos/my_photo_visibility

Get information on the visibility of the user's photo.
fields optional

Default value: desc_for_user

Selector of result fields you are interested in. The selector may contain any subset of fields, 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. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • desc_for_user - Response to the question: "Who can see my photo?".

    A LangDict object. A short paragraph of text (one or two sentences). It is intended to be read by the user himself (that is, the user who is on the photo). You should not display it to any other users.

    Keep in mind that the underlying permissions model can change in such a way that the level field becomes deprecated. The desc_for_user description however - will stay up-to-date. Consider using it instead of parsing the level on your own!

services/photos/photo

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.uni.opole.pl/services/photos/photo

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.

Get user's photo.

Important: Please avoid using this method. The preferred method of retrieving user photos is to use the photo_urls field of the services/users/user method.
user_id optional

Default value: (access token issuer)

ID of a user.
blank_photo optional

Default value: false

Boolean. By default, if you are not allowed to see the photo, then this method will return a HTTP 400 error response. Set this parameter to true if you want to receive a blank placeholder image instead.
transform optional

Default value: false

Important: Photo transformations are allowed only for Administrative Consumers. However, you can still use some basic photo transformations with the photo_urls field of the services/users/user method.

Boolean. If set to false (default):

  • USOS API will respond with the original photo, exactly as it is stored in our database, without any kind of processing. Such images can be quite big (and this applies to the blank photo placeholder too).
  • We do NOT guarantee that the original raw file will be valid, nor that it will be in a JPEG format.

If set to true:

  • USOS API will process, resize and validate the photo before it is returned to you.
  • The output will always be in the JPEG format.
  • If USOS API encounters any problems while loading the original image file, then it will respond with an empty placeholder image.
  • Please note that the image processing library that we use often fails to load images which seem to be perfectly valid when opened in different viewers. This causes USOS API to return blank placeholder in place of a valid image. We are investigating this problem. (If this is important in your case, then don't use transform.)
max_width optional

Default value: (empty string)

This parameter is required if you're using transform.

Integer in the 1..1000 range. The maximum width of the image you want to get, in pixels. The aspect ratio will be kept while resizing.
max_height optional

Default value: (empty string)

This parameter is required if you're using transform.

Integer in the 1..1000 range. The maximum height of the image you want to get, in pixels. The aspect ratio will be kept while resizing.
enlarge optional

Default value: false

Boolean. By default, the photos are resized only if they are too large (if they don't fit in the dimensions you have provided). If you set this to true, then we will also enlarge smaller photos.
cover optional

Default value: false

Boolean.

By default, the photos are resized so that the entire photo fits inside the dimensions you have provided. This means that one of the dimensions (width or height) can be smaller than the max_width or max_height.

Setting this to true forces the width and height to match your dimensions exactly, while the aspect ratio will still be kept. That means that the result may be cropped (we will decide which part of the image is best to be returned).

If you set this to true, then you must also set the enlarge parameter to true.
Plus optional 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:

If you are allowed to see the photo, then you will receive a binary stream with the photo content. If not, you will receive a HTTP 400 error response.

You can use the can_see_photo method to check if you will be able to get the photo. You can also set the blank_photo to true - if you do, you will get a HTTP 200 response regardless of your permissions.

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • insufficient_privileges - insufficient privileges to get access to this photo.

  • object_not_found - user could not be found; param_name is equal to user_id;

  • photo_not_found - user does not have a photo.

services/photos/settings

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/photos/settings

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.

Return all parameters with their values that regard photos configuration.
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 following fields and their values:

  • max_photo_file_size - an integer, maximum size (in bytes) of photo file;

  • allow_to_upload_photo - a boolean value. This parameter indicates whether users are allowed to upload photo;

  • approve_photo_automatically - a boolean value. This parameter indicates whether photos uploaded by users will be approved automatically, without administrator review.

services/photos/update_photo

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

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
https://usosapps.uni.opole.pl/services/photos/update_photo

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.

Update user's photo.
photo required A file with photo.
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 required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • method_forbidden - access to method denied.

    Possible reasons:

    • photo_uploading_disabled - photo uploading has been disabled.

  • param_invalid - parameter has invalid value.

    Possible reasons:

    • file_size_too_big - photo file size has exceeded maximum allowed size.
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)