Imgur.API Documentation

Transcription

1 Imgur.API Documentation Release Damien Dennehy May 13, 2017

2

3 Contents 1 Quick Start Get Image Get Image (synchronously - not recommended) Upload Image Upload Image (synchronously - not recommended) Authentication Register an Application Using the Imgur Api Using the Mashape Api OAuth Authorization Request Authorization Response Creating an OAuth2 token from the Redirect URL Using the OAuth2 token Getting an OAuth2 token from the Refresh Token Endpoints Account Endpoint Album Endpoint Comment Endpoint Gallery Endpoint Image Endpoint OAuth2 Endpoint Rate Limit Endpoint FAQ How do I use Imgur.API with a proxy? i

4 ii

5 Imgur.API is a.net implementation of Imgur s API. It supports Imgur s free and Mashape s commercial API endpoints. GitHub NuGet Contents 1

6 2 Contents

7 CHAPTER 1 Quick Start Get Image public async Task GetImage() { try { var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new ImageEndpoint(client); var image = await endpoint.getimageasync("image_id"); Debug.Write("Image retrieved. Image Url: " + image.link); } catch (ImgurException imgurex) { Debug.Write("An error occurred getting an image from Imgur."); Debug.Write(imgurEx.Message); } } Get Image (synchronously - not recommended) public void GetImage() { try { var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new ImageEndpoint(client); var image = endpoint.getimageasync("image_id").getawaiter().getresult(); Debug.Write("Image retrieved. Image Url: " + image.link); } catch (ImgurException imgurex) { 3

8 } } Debug.Write("An error occurred getting an image from Imgur."); Debug.Write(imgurEx.Message); Upload Image public async Task UploadImage() { try { var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new ImageEndpoint(client); IImage image; using (var fs = new FileStream(@"IMAGE_LOCATION", FileMode.Open)) { image = await endpoint.uploadimagestreamasync(fs); } Debug.Write("Image uploaded. Image Url: " + image.link); } catch (ImgurException imgurex) { Debug.Write("An error occurred uploading an image to Imgur."); Debug.Write(imgurEx.Message); } } Upload Image (synchronously - not recommended) public void UploadImage() { try { var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new ImageEndpoint(client); IImage image; using (var fs = new FileStream(@"IMAGE_LOCATION", FileMode.Open)) { image = endpoint.uploadimagestreamasync(fs).getawaiter().getresult(); } Debug.Write("Image uploaded. Image Url: " + image.link); } catch (ImgurException imgurex) { Debug.Write("An error occurred uploading an image to Imgur."); Debug.Write(imgurEx.Message); } } 4 Chapter 1. Quick Start

9 CHAPTER 2 Authentication Register an Application In order to use the Imgur api, register an application at Using the Imgur Api Once you have the application registered, you can use it by declaring an instance of the ImgurClient class. You can declare an instance using the Client ID + Client Secret, or (as of v3.7.0) just the Client ID. var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); Using the Mashape Api If you will be using the Imgur api for commercial purposes (uploading more than 1250 images per day), you will need to use the Mashape api instead of the Imgur api. Register for Mashape at Once you have the application registered, you can use it by declaring an instance of the MashapeClient class. You can declare an instance using the Client ID + Client Secret + Mashape Key, or (as of v3.7.0) just the Client ID + Mashape Key. var client = new MashapeClient("CLIENT_ID", "MASHAPE_KEY"); var client = new MashapeClient("CLIENT_ID", "CLIENT_SECRET", "MASHAPE_KEY"); More information on the Imgur api can be found at 5

10 6 Chapter 2. Authentication

11 CHAPTER 3 OAuth2 Authorization Request To access a user s account, the user must first authorize your application so that you can get an access token. The simplest way to do this is to get and then redirect to Imgur s authorization url. var endpoint = new OAuth2Endpoint(client); var authorizationurl = endpoint.getauthorizationurl(oauth2responsetype.token_type); The authorization url will look similar to this: Once you have the url, your application must redirect to it. How you redirect will depend on your application. Some common scenarios are listed here. Using Windows Universal Apps Windows.System.Launcher.LaunchUriAsync(new Uri(authorizationUrl)); Using ASP.NET MVC return Redirect(authorizationUrl); Authorization Response Once the user authorizes the application, Imgur will then redirect back to your application s Redirect URL. The Redirect URL is configured on Imgur under your account settings. 7

12 The Redirect URL can be a localhost entry or an external url. In either case you will need a web server at this address with the ability to parse the url components. Code Response If you requested a Code OAuth2ResponseType (OAuth2ResponseType.Code) then the response from Imgur is pretty easy to parse. For example, if your Redirect URL is then a successful authorisation response from Imgur to this Redirect URL will look similar to this: The response contains the code value that should be parsed and stored by your application. Once you have parsed it, a request to Imgur must be sent to get the OAuth2 token. Note you must use the Client Secret for this. var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new OAuth2Endpoint(client); var token = await endpoint.gettokenbycodeasync(code); Token Response A Token OAuth2ResponseType (OAuth2ResponseType.Token) contains all the data you need to create a token. For example, if your Redirect URL is then a successful authorisation response from Imgur to this Redirect URL will look similar to this: access_token=access_token_value &expires_in= &token_type=bearer &refresh_token=refresh_token_value &account_username=bob &account_id= The response will contain several values that should be parsed and stored by your application. access_token - The user s access token for this session. refresh_token - The user s refresh token which should be used to refresh the access_token when it expires. token_type - The type of token that should be used for authorization. account_id - The user s account id. account_username - The user s account username. expires_in - The time in seconds when the user s access token expires. Default is one month Note the hash # in the url. This is a fragment and is not returned to server side code. You may need to use JavaScript to parse the values instead of server side code. Creating an OAuth2 token from the Redirect URL. Using the Redirect URL values, an OAuth2 Token can be created. var token = new OAuth2Token("ACCESS_TOKEN", "REFRESH_TOKEN", "TOKEN_TYPE", "ACCOUNT_ID", "ACCOUNT_USERNAME", EXPIRES_IN); The token should be stored by your application. This will save your application from constructing a new token on each endpoint request. 8 Chapter 3. OAuth2

13 Using the OAuth2 token. Using the OAuth2 token can be done in two ways: 1. You may use it in the client s constructor: var client = new ImgurClient("CLIENT_ID", token); var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET", token); 2. You may also switch or set the token explicitly using the client s SetOAuth2Token method: client.setoauth2token(token); Getting an OAuth2 token from the Refresh Token. If the access token has expired but you still have the refresh token, you can request a new OAuth2 token. Note that you must use the Client Secret to get the refresh token. var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new OAuth2Endpoint(client); var token = endpoint.gettokenbyrefreshtokenasync("refresh_token"); More information on Imgur s OAuth2 implementation can be found at #authorization-and-oauth 3.4. Using the OAuth2 token. 9

14 10 Chapter 3. OAuth2

15 CHAPTER 4 Endpoints Account Endpoint DeleteAlbumAsync Delete an Album with a given id. OAuth authentication required. var deleted = await endpoint.deletealbumasync("album_id", "USERNAME"); DeleteCommentAsync Delete a comment. OAuth authentication required. var deleted = await endpoint.deletecommentasync(comment_id, "USERNAME"); DeleteImageAsync Deletes an Image. OAuth authentication required. var deleted = await endpoint.deleteimageasync("delete_hash", "USERNAME"); 11

16 GetAccountAsync Request standard user information. var account = await endpoint.getaccountasync("username"); GetAccountFavoritesAsync Returns the users favorited images. OAuth authentication required. var favourites = await endpoint.getaccountfavoritesasync(); GetAccountGalleryFavoritesAsync Return the images the user has favorited in the gallery. var favourites = await endpoint.getaccountgalleryfavoritesasync("username"); GetAccountSettingsAsync Returns the account settings. OAuth authentication required. var submissions = await endpoint.getaccountsettingsasync(); GetAccountSubmissionsAsync Return the images a user has submitted to the gallery. var submissions = await endpoint.getaccountsubmissionsasync("username"); GetAlbumAsync Get additional information about an album, this works the same as the Album Endpoint. var album = await endpoint.getalbumasync("album_id", "USERNAME"); 12 Chapter 4. Endpoints

17 GetAlbumCountAsync Return the total number of albums associated with the account. var count = await endpoint.getalbumcountasync("username"); GetAlbumIdsAsync Return a list of all of the album IDs. var albumids = await endpoint.getalbumidsasync("username", PAGE); GetAlbumsAsync Get all the albums associated with the account. Must be logged in as the user to see secret and hidden albums. var albums = await endpoint.getalbumsasync("username", PAGE); GetCommentAsync Return information about a specific comment. var comment = await endpoint.getcommentasync(comment_id, "USERNAME"); GetCommentCountAsync Return a count of all of the comments associated with the account. var count = await endpoint.getcommentcountasync("username"); GetCommentIdsAsync Return a list of all of the comment IDs. var commentids = await endpoint.getcommentidsasync("username"); 4.1. Account Endpoint 13

18 GetCommentsAsync Return the comments the user has created. var comments = await endpoint.getcommentsasync("username"); GetGalleryProfileAsync Returns the totals for the gallery profile. var profile = await endpoint.getgalleryprofileasync("username"); GetImageAsync Return information about a specific image. var image = await endpoint.getimageasync("image_id", "USERNAME"); GetImageCountAsync Returns the total number of images associated with the account. OAuth authentication required. var count = await endpoint.getimagecountasync(); GetImageIdsAsync Returns a list of Image IDs that are associated with the account. OAuth authentication required. var imageids = await endpoint.getimageidsasync(); GetImagesAsync Return all of the images associated with the account. OAuth authentication required. var images = await endpoint.getimagesasync(); 14 Chapter 4. Endpoints

19 GetNotificationsAsync Returns all of the notifications for the user. OAuth authentication required. var notifications = await endpoint.getnotificationsasync(false); SendVerification Async Sends an to the user to verify that their is valid to upload to gallery. OAuth authentication required. var sent = await endpoint.sendverification async(); UpdateAccountSettingsAsync Updates the account settings for a given user. OAuth authentication required. var updated = await endpoint.updateaccountsettingsasync(); Verify Async Checks to see if user has verified their address. OAuth authentication required. var verified = await endpoint.verify async(); Album Endpoint AddAlbumImagesAsync Adds a list of ids to the album. For anonymous albums, the deletehash that is returned at creation must be used. var endpoint = new AlbumEndpoint(client); var added = await endpoint.addalbumimagesasync("album_id_or_delete_hash", new List<string> {"IMAGE_ID", "IMAGE_ID", "IMAGE_ID"}); CreateAlbumAsync Create a new album Album Endpoint 15

20 var endpoint = new AlbumEndpoint(client); var album = await endpoint.createalbumasync(); DeleteAlbumAsync Delete an album with a given ID. You are required to be logged in as the user to delete the album. For anonymous albums, the deletehash that is returned at creation must be used. var endpoint = new AlbumEndpoint(client); var deleted = await endpoint.deletealbumasync("album_id_or_delete_hash"); FavoriteAlbumAsync Favorite an album with a given ID. The user is required to be logged in to favorite the album. var endpoint = new AlbumEndpoint(client); var favorited = await endpoint.favoritealbumasync("album_id"); GetAlbumAsync Get information about a specific album. var endpoint = new AlbumEndpoint(client); var album = await endpoint.getalbumasync("album_id"); GetAlbumImageAsync Get information about an image in an album. var endpoint = new AlbumEndpoint(client); var image = await endpoint.getalbumimageasync("image_id", "ALBUM_ID"); GetAlbumImagesAsync Return all of the images in the album. var endpoint = new AlbumEndpoint(client); var images = await endpoint.getalbumimagesasync("album_id"); 16 Chapter 4. Endpoints

21 RemoveAlbumImagesAsync Removes a list of ids from the album. For anonymous albums, the deletehash that is returned at creation must be used. var endpoint = new AlbumEndpoint(client); var added = await endpoint.removealbumimagesasync("album_id_or_delete_hash", new List<string> {"IMAGE_ID", "IMAGE_ID", "IMAGE_ID"}); SetAlbumImagesAsync Sets the images for an album, removes all other images and only uses the images in this request. For anonymous albums, the deletehash that is returned at creation must be used. var endpoint = new AlbumEndpoint(client); var set = await endpoint.setalbumimagesasync("album_id_or_delete_hash", new List<string> {"IMAGE_ID", "IMAGE_ID", "IMAGE_ID"}); UpdateAlbumAsync Update the information of an album. For anonymous albums, the deletehash that is returned at creation must be used. var endpoint = new AlbumEndpoint(client); var updated = await endpoint.updatealbumasync("album_id_or_delete_hash"); Comment Endpoint CreateCommentAsync Creates a new comment, returns the ID of the comment. OAuth authentication required. var endpoint = new CommentEndpoint(client); var commentid = await endpoint.createcommentasync("comment", "GALLERY_ITEM_ID"); CreateReplyAsync Create a reply for the given comment, returns the ID of the comment. OAuth authentication required. var endpoint = new CommentEndpoint(client); var commentid = await endpoint.createreplyasync(comment, "GALLERY_ITEM_ID", "PARENT_ COMMENT_ID"); 4.3. Comment Endpoint 17

22 DeleteCommentAsync Delete a comment by the given id. OAuth authentication required. var endpoint = new CommentEndpoint(client); var deleted = await endpoint.deletecommentasync(comment_id); GetCommentAsync Get information about a specific comment. var endpoint = new CommentEndpoint(client); var comment = await endpoint.getcommentasync(comment_id); GetRepliesAsync Get the comment with all of the replies for the comment. var endpoint = new CommentEndpoint(client); var comment = await endpoint.getrepliesasync(comment_id); ReportCommentAsync Report a comment for being inappropriate. OAuth authentication required. var endpoint = new CommentEndpoint(client); var reported = await endpoint.reportcommentasync(comment_id, REPORT_REASON); VoteCommentAsync Vote on a comment. OAuth authentication required. var endpoint = new CommentEndpoint(client); var voted = await endpoint.votecommentasync(comment_id, VOTE); Gallery Endpoint CreateGalleryItemCommentAsync Create a comment for an item. OAuth authentication required. var commentid = await endpoint.creategalleryitemcommentasync("comment", "GALLERY_ITEM_ ID"); 18 Chapter 4. Endpoints

23 CreateGalleryItemCommentReplyAsync Reply to a comment that has been created for an item. OAuth authentication required. var commentid = await endpoint.creategalleryitemcommentreplyasync("comment", "GALLERY_ ITEM_ID", "PARENT_COMMENT_ID "); GetGalleryAlbumAsync Get additional information about an album in the gallery. var album = await endpoint.getgalleryalbumasync("album_id"); GetGalleryAsync Returns the images in the gallery. var images = await endpoint.getgalleryasync(); GetGalleryImageAsync Get additional information about an image in the gallery. var image = await endpoint.getgalleryimageasync("image_id"); GetGalleryItemCommentAsync Get information about a specific comment. var comment = await endpoint.getgalleryitemcommentasync(comment_id, "GALLERY_ITEM_ID "); 4.4. Gallery Endpoint 19

24 GetGalleryItemCommentCountAsync The number of comments on an item. var count = await endpoint.getgalleryitemcommentcountasync("gallery_item_id"); GetGalleryItemCommentIdsAsync List all of the IDs for the comments on an item. var commentids = await endpoint.getgalleryitemcommentidsasync("gallery_item_id"); GetGalleryItemCommentsAsync Get all comments for a gallery item. var comments = await endpoint.getgalleryitemcommentsasync("gallery_item_id"); GetGalleryItemTagsAsync View tags for a gallery item. var tags = await endpoint.getgalleryitemtagsasync("gallery_item_id"); GetGalleryItemVotesAsync Get the vote information about an image. var votes = await endpoint.getgalleryitemvotesasync("gallery_item_id"); GetGalleryTagAsync View images for a gallery tag. var tag = await endpoint.getgallerytagasync("tag"); 20 Chapter 4. Endpoints

25 GetGalleryTagImageAsync View a single image in a gallery tag. var image = await endpoint.getgallerytagimageasync("gallery_item_id", "TAG"); GetMemesSubGalleryAsync View images for memes subgallery. var memes = await endpoint.getmemessubgalleryasync(); GetMemesSubGalleryImageAsync View a single image in the memes gallery. var image = await endpoint.getmemessubgalleryimageasync("image_id"); GetRandomGalleryAsync Returns a random set of gallery images. var images = await endpoint.getrandomgalleryasync(); GetSubredditGalleryAsync View gallery images for a subreddit. var images = await endpoint.getsubredditgalleryasync("subreddit"); GetSubredditImageAsync View a single image in the subreddit. var image = await endpoint.getsubredditimageasync("image_id", "SUBREDDIT"); 4.4. Gallery Endpoint 21

26 PublishToGalleryAsync Share an Album or Image to the Gallery. OAuth authentication required. var published = await endpoint.publishtogalleryasync("gallery_item_id", "TITLE"); RemoveFromGalleryAsync Remove an image from the gallery. OAuth authentication required. var removed = await endpoint.removefromgalleryasync("gallery_item_id"); ReportGalleryItemAsync Report an item in the gallery. OAuth authentication required. var reported = await endpoint.reportgalleryitemasync("gallery_item_id", REASON); SearchGalleryAsync Search the gallery with a given query string. var images = await endpoint.searchgalleryasync("query"); SearchGalleryAdvancedAsync Search the gallery with a given query string. var images = await endpoint.searchgalleryadvancedasync("all_words_query", "ANY_WORDS_ QUERY", "EXACT_WORDS_QUERY", "NOT_ WORDS_QUERY"); VoteGalleryItemAsync Vote for an item. Send the same value again to undo a vote. OAuth authentication required. var voted = await VoteGalleryItemAsync("GALLERY_ITEM_ID", VOTE); 22 Chapter 4. Endpoints

27 VoteGalleryTagAsync Vote for a tag. Send the same value again to undo a vote. OAuth authentication required. var voted = await VoteGalleryTagAsync("GALLERY_ITEM_ID", "TAG", VOTE); Image Endpoint DeleteImageAsync Deletes an image. For an anonymous image, the deletehash that is returned at creation must be used. If the image belongs to your account then passing the ID of the image is sufficient. var endpoint = new ImageEndpoint(client); var deleted = await endpoint.deleteimageasync("image_id_or_delete_hash"); FavoriteImageAsync Favorite an image with the given ID. OAuth authentication required. var endpoint = new ImageEndpoint(client); var favorited = await endpoint.favoriteimageasync("image_id"); GetImageAsync Get information about an image. var endpoint = new ImageEndpoint(client); var image = await endpoint.getimageasync("image_id"); UpdateImageAsync Updates the title or description of an image. For an anonymous image, the deletehash that is returned at creation must be used. var endpoint = new ImageEndpoint(client); var updated = await endpoint.updateimageasync("image_id_or_delete_hash", "TITLE", "DESCRIPTION"); UploadImageBinaryAsync Upload a new image using a binary file Image Endpoint 23

28 var endpoint = new ImageEndpoint(client); var file = System.IO.File.ReadAllBytes(@"IMAGE_LOCATION"); var image = await endpoint.uploadimagebinaryasync(file); UploadImageStreamAsync Upload a new image using a stream. var endpoint = new ImageEndpoint(client); IImage image; using (var fs = new FileStream(@"IMAGE_LOCATION", FileMode.Open)) { image = await endpoint.uploadimagestreamasync(fs); } UploadImageUrlAsync Upload a new image using a URL. var endpoint = new ImageEndpoint(client); var image = await endpoint.uploadimageurlasync("image_url"); OAuth2 Endpoint GetAuthorizationUrl Creates an authorization url that can be used to authorize access to a user s account. var endpoint = new OAuth2Endpoint(client); var redirecturl = endpoint.getauthorizationurl(response_type); GetTokenByCodeAsync After the user authorizes, the pin is returned as a code to your application via the redirect URL you specified during registration, in the form of a regular query string parameter. var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new OAuth2Endpoint(client); var token = await endpoint.gettokenbycodeasync("code"); GetTokenByPinAsync After the user authorizes, they will receive a PIN code that they copy into your app. 24 Chapter 4. Endpoints

29 var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new OAuth2Endpoint(client); var token = await endpoint.gettokenbypinasync("pin"); GetTokenByRefreshTokenAsync If a user has authorized their account but you no longer have a valid access token for them, then a new one can be generated by using the refresh token. var client = new ImgurClient("CLIENT_ID", "CLIENT_SECRET"); var endpoint = new OAuth2Endpoint(client); var token = await endpoint.gettokenbyrefreshtokenasync("refresh_token"); Rate Limit Endpoint GetRateLimitAsync Gets remaining credits for the application. var endpoint = new RateLimitEndpoint(client); var ratelimit = await endpoint.getratelimitasync(); 4.7. Rate Limit Endpoint 25

30 26 Chapter 4. Endpoints

31 CHAPTER 5 FAQ How do I use Imgur.API with a proxy? If your application requires the use of a proxy, then this can be set in one of two ways: 1. Configure proxy in the App.Config or Web.config file. Add the following section to your config file. <system.net> <defaultproxy usedefaultcredentials="true" /> </system.net> 2. Configure proxy programmatically. Set the DefaultWebProxy credentials before any API endpoints are used. System.Net.WebRequest.DefaultWebProxy.Credentials = System.Net.CredentialCache.DefaultNetworkCredentials; A System.Net.Http.HttpRequestException exception is thrown when a proxy is required and the current credentials are not valid. You should catch this exception if you suspect your application will have proxy issues. 27