/ 
ImgurAPI-Client-1.0.7
River stage zero No dependents
/ ImgurAPI::Client

NAME

ImgurAPI::Client - Imgur API client

DESCRIPTION

This is a client module for interfacing with the Imgur API.

SYNOPSIS

Instantiation

use ImgurAPI::Client;

my $client = ImgurAPI::Client->new({
    'client_id'    => 'your_client_id',
    'access_token' => 'your_access_token'
});

my $upload = $client->image_upload("helloimgur.png", 'file', {title => 'title', description => 'desc'});
my $image_info = $client->image($upload->{'data'}->{'id'};

Authorization

Imgur uses OAuth 2.0 for authentication. OAuth 2.0 has four steps: registration, authorization, making authenticated requests and getting new access tokens after the initial one expires using a refresh token and client secret.

After registering a client application with Imgur here, the user will need to manually authorize it. Generate a authorization url using the oauth2_authorize_url method and redirect the user to the generated url. The user will be prompted to authorize the application and upon authorization, the user will be redirected to the callback endpoint URL that was specified during application registration. The callback endpoint should collect the access token and refresh token and store them somewhere your code on the backend can pull the access token from and then pass it to the client. You can also visit the authorization url in the browser and manually pull the access token, refresh token and other parameters out of the redirect url and store them somewhere your code can pull them without having a collector endpoint setup. View the official imgur documentation for authorization here.

Authentication

The client can be authenticated by setting the access token and client id. Those can be set a couple of ways. The first way is to do it is by passing them to the constructor:

my $client = ImgurAPI::Client->new({
    'client_id'    => 'your_client_id',
    'access_token' => 'your_access_token'
});

The second way is to use the setter methods:

$client->set_access_token('your_access_token');
$client->set_client_id('your_client_id');

METHODS

new

$client = ImgurAPI::Client->new(\%args);

Valid constructor arguments are:

  • client_id - Client identifier used for authorization, refresh token requests and unauthenticated requests.

  • client_secret - Client secret used for acquiring a refresh token.

  • access_key - Access token used to authenticate requests.

  • rapidapi_key - Commercial use api key provided by RapidAPI.

  • format_type - Api endpoint response format type. Options are json (default) and xml.

  • oauth_cb_state - A parameter that's appended to the OAuth2 authorization callback URL. May be useful if you want to pass along a tracking value to the callback endpoint / collector.

A getter and setter method is provided for each constructor arg.

SETTER METHODS

set_access_token

$client->set_access_token('your_access_token');

set_client_id

$client->set_client_id('your_client_id');

set_client_secret

$client->set_client_secret('your_client_secret');

set_format_type

$client->set_format_type('xml');

set_oauth_cb_state

$client->set_oauth_cb_state('your_oauth_cb_state');

set_rapidapi_key

$client->set_rapidapi_key('rapidapi_key');

GETTER METHODS

access_token

$access_tok = $client->access_token;

client_id

$client_id = $client->client_id;

client_secret

$client_secret = $client->client_secret;

format_type

$format_type = $client->format_type;

oauth_cb_state

$oauth_cb_state = $client->oauth_cb_state;

rapidapi_key

$rapidapi_key = $client->rapidapi_key;

response

$response = $client->response;

This method will return the last response object from the last request.

response_content

$response_content = $client->response_content;

This method will return the last response content from the last request.

ratelimit_headers

$ratelimit_headers = $client->ratelimit_headers;

This method will return a hashref containing the rate limit headers from the last request. The keys returned are:

  • userlimit - The total credits that can be allocated.

  • userremaining - The total credits remaining.

  • userreset - Timestamp (unix epoch) for when the credits will be reset.

  • clientlimit - Total credits that can be allocated for the application in a day.

  • clientremaining - Total credits remaining for the application in a day.

API REQUEST METHODS

ACCOUNT

account
$resp = $client->account($username);

Get account information for a given username. Pass me as the username to get the account information for the authenticated user.

account_album
$resp = $client->account_album($username, $album_id);

Get information about a specific account album. Pass me as the username to get the account information for the authenticated user.

account_album_count
$resp = $client->account_album_count($username);

Get the total number of albums associated with an account. Pass me as the username to get the account information for the authenticated user.

account_album_delete
$resp = $client->account_album_delete($username, $album_id);

Delete a specific album. Pass me as the username to get the account information for the authenticated user.

account_album_ids
$resp = $client->account_album_ids($username, \%opts);

Get all the album ids associated with the account. Pass me as the username to get the account information for the authenticated user.

Valid options are:

  • page - Page number

account_albums
$resp = $client->account_albums($username, \%opts);

Valid options are:

  • page - Page number

account_block_status
$resp = $client->account_block_status($username);

Get the current block status for a user.

account_block_create
$resp = $client->account_block_create($username);

Block a user.

account_block_delete
$resp = $client->account_block_delete($username);

Unblock a user.

account_blocks
$resp = $client->account_blocks;

Get the list of usernames that have been blocked.

account_comment
$resp = $client->account_comment($username, $comment_id);

Get information about a specific account comment.

account_comment_count
$resp = $client->account_comment_count($username);

Get the total number of comments associated with the account username.

account_comment_delete
$resp = $client->account_comment_delete($username, $comment_id);

Delete a specific account comment.

account_comment_ids
$resp = $client->account_comment_ids($username, \%opts);

Valid options are:

  • page - Page number

  • sort - Sort order. Options are best, worst and newest (default)

account_comments
$resp = $client->account_comments($username, \%opts);

Valid options are:

  • page - Page number

  • sort - Sort order. Options are best, worst and newest (default)

account_delete
$resp = $client->account_delete($password, \%opts);

Valid options are:

  • reasons - Array reference of reasons for deleting the account

  • feedback - Feedback in the form of a string for Imgur.

account_favorites
$resp = $client->account_favorites($username, \%opts);

Valid options are:

  • page - Page number

  • sort - Sort order. Options are oldest or newest (default)

$resp = $client->account_gallery_favorites($username, \%opts);

Valid options are:

  • page - Page number

  • sort - Sort order. Options are oldest or newest (default)

account_image
$resp = $client->account_image($username, $image_id);

Get information about a specific image in the account.

account_image_count
$resp = $client->account_image_count($username);

Get the total number of images associated with the account.

account_image_delete
$resp = $client->account_image_delete($username, $image_id);

Delete a specific image.

account_image_ids
$resp = $client->account_image_ids($username, \%opts);

Valid options are:

  • page - Page number

account_images
$resp = $client->account_images($username, \%opts);

Valid options are:

  • page - Page number

account_reply_notifications
$resp = $client->account_reply_notifications($username, \%opts);

Valid options are:

  • new - Boolean value. True for unviewed notifications and false for viewed notifications.

account_settings
$resp = $client->account_settings($username);

Get account settings for a given username.

account_settings_update
$resp = $client->account_settings_update($username, \%opts);

Update an account's settings.

Valid options are:

  • bio - A string for the bio.

  • public_images - A boolean value to set images to public or not by default.

  • messaging_enabled - A boolean value to allow messaging or not.

  • accepted_gallery_terms - A boolean value to accept the gallery terms.

  • username - A valid username between 4 and 63 alphanumeric characters.

  • show_mature - A boolean value to show mature images in gallery list endpoints.

  • newsletter_subscribed - A boolean value, true to subscribe to the newsletter, false to unsubscribe from the newsletter.

account_submissions
$resp = $client->account_submissions($username, \%opts);

Valid options are:

  • page - Page number

account_tag_follow
$resp = $client->account_tag_follow($tag);

Follow a tag.

account_tag_unfollow
$resp = $client->account_tag_unfollow($tag);

Unfollow a tag.

account_verify_email_send
$resp = $client->account_verify_email_send($username);

Send a verification email.

account_verify_email_status
$resp = $client->account_verify_email_status($username);

Get the status of the verification email.

ALBUM

album
$resp = $client->album($album_id);

Get information about a specific album.

album_create
$resp = $client->album_create(\%opts);

  • ids - Array reference of image ids.

  • title - Title of the album.

  • description - Description of the album.

  • cover - Image id of the cover image.

album_delete
$resp = $client->album_delete($album_id);

Delete an album.

album_favorite
$resp = $client->album_favorite($album_id);

Favorite an album.

album_image
$resp = $client->album_image($album_id, $image_id);

Get information about a specific image in an album.

album_images
$resp = $client->album_images($album_id);

Get all the images in an album.

album_images_add
$resp = $client->album_images_add($album_id, \@image_ids);

Add images to an album.

album_images_delete
$resp = $client->album_images_delete($album_id, \@image_ids);

Delete images from an album.

album_images_set
$resp = $client->album_images_set($album_id, \@image_ids);

Set the images for an album.

album_update
$resp = $client->album_update($album_id, \%opts);

Update an album. Valid options are:

  • ids - Array reference of image ids.

  • title - Title of the album.

  • description - Description of the album.

  • cover - Image id of the cover image.

COMMENT

comment
$resp = $client->comment($comment_id);

Get information about a specific comment.

comment_create
$resp = $client->comment_create($image_id, $comment);

Create a new comment on an image.

comment_delete
$resp = $client->comment_delete($comment_id);

Delete a comment.

comment_replies
$resp = $client->comment_replies($comment_id);

Get the replies for a specific comment.

comment_reply
$resp = $client->comment_reply($image_id, $comment_id, $comment);

Create a new reply to a comment.

comment_report
$resp = $client->comment_report($comment_id, $reason);

Report a comment with a reason. Valid reasons are:

  • 1 - Doesn't belong on Imgur

  • 2 - Spam

  • 3 - Abusive

  • 4 - Mature content not marked as mature

  • 5 - Pornography

comment_vote
$resp = $client->comment_vote($comment_id, $vote);

Cast a vote on a comment. Valid vote values are up, down and veto.

$resp = $client->gallery(\%opts);

Get gallery images.

$resp = $client->gallery_album($album_id);
$resp = $client->gallery_image($image_id);
$resp = $client->gallery_item($item_id);
$resp = $client->gallery_item_comment($item_id, $comment);
$resp = $client->gallery_item_comment_info($item_id, $comment_id);
$resp = $client->gallery_item_comments($item_id);
$resp = $client->gallery_item_report($item_id, \%opts);
$resp = $client->gallery_item_tags($item_id);
$resp = $client->gallery_item_tags_update($item_id, \@tags);
$resp = $client->gallery_item_vote($item_id, $vote);
$resp = $client->gallery_item_votes($item_id);
$resp = $client->gallery_image_remove($image_id);
$resp = $client->gallery_search('query', \%opts, \%advanced);
$resp = $client->gallery_share_image($image_id , $title, \%opts);
$resp = $client->gallery_share_album($album_id, $title, \%opts);
$resp = $client->gallery_subreddit('subreddit', \%opts);
$resp = $client->gallery_subreddit_image('subreddit', $image_id);
$resp = $client->gallery_tag($tag, \%opts);
$resp = $client->gallery_tag_info($tag);
$resp = $client->gallery_tags;

IMAGE

image
$resp = $client->image($image_id);

Get information about a specific image.

image_upload
$resp = $client->image_upload('image_path', 'file', {title => 'title', description => 'description'});

Upload an image or video to imgur. The second argument is the type of the first argument. It can be either file or url.

image_delete
$resp = $client->image_delete($image_id);

Delete an image.

image_favorite
$resp = $client->image_favorite($image_id);

Favorite an image.

image_update
$resp = $client->image_update($image_id, {title => 'title', description => 'description'});

Update an image.

FEED

feed
$resp = $client->feed;

Get the authenticated user's feed.

AUTHOR

Dillan Hildebrand

LICENSE

MIT