Tutorial: Connecting to the SoFurry API

From SoFurry
Revision as of 10:10, 6 March 2016 by TerraBAS (talk | contribs) (→‎Example)
Jump to: navigation, search

This tutorial will lead you through the steps necessary to connect to the SoFurry REST APIs using OAuth 2.0.

Client requirements

  • The client must be able to handle SSL certificates and HTTPS URLs.
  • The client must be able to process either JSON, XML or PHP-type responses.
  • The client must be registered on SoFurry and have received a client_ID and client_secret.

Authorizing the application

There are 2 ways to authorize your application using OAuth 2.0. SoFurry is currently only supporting "Authorization codes" for external application. "Client credentials" will be available in the future.

Read more about the auth-types here.

Authorization code grant type

Basics

When using the Authorization code grant type, the auth flow is as following:

  • Client sends a authorization request to https://www.sofurry.com/auth/authorize, including the client_id, client_secret and grant_type (in this case, the grant_type would be "code").
    • The server answers with the HTML of the authorization page. The client must display this response and the user has to click on the "Authorize" button.
      Authorization denied
      If the users denies the authorization, the server will redirect the client to the redirect_URL (Set in the SF application manager or as a parameter in the authorization request).
      Authorization granted
      If the user grants an app access to the user data, the server will redirect the client to the redirect_URL, including the code parameter (authorization code).
  • Now that the client has received the authorization code from the server, it must be exchanged for an access_token within 180 seconds (after that, the code will be invalid and the client will have to request a new one). To exchange the code with an access token, the client has to send a request to https://www.sofurry.com/auth/token, including the client_id, client_secret and the code it received before.
    • The server will reply to a valid code with an access_token, refresh_token, refresh_time, and token_type. You will need the access_token to access the SoFurry REST APIs. The refresh_token can be exchanged for a new access_token later on when the access_token times out.
  • After receiving the access_token, the client can now send requests directly to the API and authenticate by only including the access_token in the request parameters. A request URL for the v3 API would then look like this: https://api.sofurry.com/v3/user/details?access_token=j84u43834zhujg9u872z4.


Example

Step 1: Client sends an authorization request to https://www.sofurry.com/auth/authorize

Request URL (example): 

https://www.sofurry.com/auth/authorize?response_type=code&client_id=fe523da3869cfrue8hd145fas24e8366&client_secret=824013cf4et9cfe9e8cfgtr8a3f61619&redirect_uri=https://myredirecturi.com/cb&state=xyz

Don't forget to include the "state" parameter ("state" can be anything. This string will be sent to the redirection URL by the server [untouched])!

Server response (HTML preview):

Error creating thumbnail: File missing


Server response when cancelled (redirection to): 

https://myredirecturi.com/cb?error=access_denied&error_description=The+user+denied+access+to+your+application&state=xyz

Server response when authorized (redirection to): 

https://myredirecturi.com/cb?code=dsa4e6806dd6dccbase8ba35649e58047gfc49c9&state=xyz


Step 2: Exchanging authorization code with an access token

Request URL (example):

Note: This has to be a POST request! 

https://www.sofurry.com/auth/token?grant_type=authorization_code&code=dsa4e6806dd6dccbase8ba35649e58047gfc49c9

Server response: 

{
  "access_token": "373d89e1dfd3cdb8aa7a72eefba1a44t8999s3e9",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": null,
  "refresh_token": "aff7caad98s642ce64e8b227078466d92acb7f04"
}


Step 3: Accessing the SoFurry APIs

Now that we have everything we need to access the SoFurry API, we can finally send the first request.


As an example, we try to get the user's data by sending a request to https://api.sofurry.com/v3/user/details and include the access_token we received before.

API request URL example: 

https://api.sofurry.com/v3/user/details?access_token=373d89e1dfd3cdb8aa7a72eefba1a44t8999s3e9

Server response: <syntaxhighlight lang="JSON" line> { 

  "userID":"379876",
  "username":"TerraBAS",
  "alias":"terrabas",
  "type":"Snuggbud, Chocolate bro, Artist, Site Developer",
  "species":"Husky",
  "gender":"1",
  "orientation":"3",
  "mateshipStatus":"5",
  "country":"Austria",
  "city":"",
  "registrationDate":"23 Feb 2015",
  "description":"Hey there, welcome to<\/span><\/strong> my page!<\/strong>
My name is TerraBAS, but I'm mostly called Terra.

I'm an Austrian, playful husky that is unbelievably fluffy :3

Things I love to do:
Hangin' out with friends, some sports (like cycling), programming (especially C# and Java), producing music, drawing, and much more...

If you want to know more about me, just send me a PM or add me on Skype, I don't bite ;P


Also, I'm the programmer of the SoFurry Android app, so if you have any questions or feedback, you can tell me.
<\/span>
",
  "adultdescription":"",
  "iswatched":false,
  "usericon":"http:\/\/www.sofurrybeta.com\/std\/avatar?user=379876&character=0&clevel=2",
  "profilebanner":"http:\/\/www.sofurrybeta.com\/std\/banner?user=379876",
  "loves":"",
  "likes":"",
  "tolerates":"",
  "hates":"",
  "stats":{
     "profileViewCount":"583",
     "submissionCount":"1",
     "submissionViewCount":"26",
     "commentCount":"3",
     "commentPostedCount":"6"
  }

} </syntaxhighlight>

And that's it. You successfully authenicated with the SoFurry API and are now able to use the API.

For all available API calls, look here

Retrieved from "http://wiki.sofurry.com/w/index.php?title=Tutorial:_Connecting_to_the_SoFurry_API&oldid=1984"