Difference between revisions of "SoFurry 2.0 API"

From SoFurry
Jump to: navigation, search
(Created page with "== Getting User Profiles == === Request URL === http://api2.sofurry.com/std/getUserProfile === Parameters === * id = numerical ID of the user whose profile you want. Optio...")
 
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
 +
{| style="width: 100%; background: #FF6600; margin: 1.2em 0 6px 0; border: 1px solid #ddd;"
 +
| style="width: 100%; color: #000;" |
 +
{| style="width: 100%; border: none; background: none;margin: 0.7em 0 0 0;"
 +
| style="width: 100%; text-align: center; white-space: nowrap; color: #000;" |
 +
NOTE: The API is currently being updated. This information is subject to change fundamentally shortly.
 +
|}
 +
|}
 +
== Browse submissions ==
 +
 +
=== Request URL ===
 +
    https://api2.sofurry.com/browse/all/art?format=json
 +
    https://api2.sofurry.com/browse/all/stories?format=json
 +
    https://api2.sofurry.com/browse/all/music?format=json
 +
    https://api2.sofurry.com/browse/all/photos?format=json
 +
    https://api2.sofurry.com/browse/all/journals?format=json
 +
 +
=== Parameters ===
 +
* sortby = date, popularity, length, title, random
 +
* from = all time, this year, this month, this week, yesterday, today
 +
* rating = clean, adult, clean adult (max rating, leave empty to show all)
 +
 +
=== Returned data ===
 +
 +
    {
 +
        "title": "SoFurry - All Art",
 +
        "items": [
 +
            {
 +
                "thumbnail": "https://www.sofurryfiles.com/std/thumb?page=12345",
 +
                "contentlevel": "Clean", (can be clean, adult, extreme)
 +
                "id": "12345",
 +
                "title": "Submission Title",
 +
                "author": "author name",
 +
                "link": "http://api2.sofurry.com/view/12345",
 +
                "postTime": "1430157763",
 +
                "tags": "Tags, separated, by, commas",
 +
                "description": "Lengthy description"
 +
            },
 +
            ....
 +
        ]
 +
    }
 +
 +
== Browse user submissions ==
 +
 +
=== Request URL ===
 +
    https://api2.sofurry.com/browse/user/art?uid=1234&format=json
 +
 +
=== Parameters ===
 +
* uid = optional user ID to show only this user's submissions
 +
 +
=== Returned data ===
 +
 +
Same format as regular browse request
 +
 +
 +
== Search submissions ==
 +
 +
=== Request URL ===
 +
    https://api2.sofurry.com/browse/search?search=Searchterm1,Searchterm2&format=json
 +
 +
=== Parameters ===
 +
* search = Search tags separated by comma. To do a fulltext search, enclose the search term with "quotation marks"
 +
* filter = all, stories, artwork, stories, photos, journals (optional, defaults to all)
 +
* sort = date, daterev, popularity
 +
* daterange = all, day, week, month, 6 months, year
 +
* minlevel = 0 (0=clean, 1=adult, 2=extreme)
 +
* maxlevel = 2 (0=clean, 1=adult, 2=extreme)
 +
 +
=== Returned data ===
 +
 +
    { 
 +
        "searchType":"all",
 +
        "searchTerm":"orca",
 +
        "items":[ 
 +
            { 
 +
                "contentlevel":"clean",
 +
                "id":852521,
 +
                "tags":"Fox, Transformation, Dragon, Orca, Muscle Growth, Cock Growth, Toys, Growth, M/M, Latex, M/solo, Machines, Foot growth",
 +
                "title":"Latex Stream Story 3: A Pleasure to Meet You",
 +
                "author":"draconicon",
 +
                "link":"http://www.sofurry.com/view/852521",
 +
                "postTime":1430018009
 +
            },
 +
            ...
 +
        ]
 +
    }
 +
 +
 +
 
== Getting User Profiles ==
 
== Getting User Profiles ==
  
Line 6: Line 95:
 
=== Parameters ===
 
=== Parameters ===
 
  * id = numerical ID of the user whose profile you want. Optional. If omitted, the system will send your own profile data.
 
  * id = numerical ID of the user whose profile you want. Optional. If omitted, the system will send your own profile data.
 +
* username = name of the user whose profile you want. Optional. Can be used instead of id, for if you don't know the user id.
  
 
=== Returned data ===
 
=== Returned data ===
Line 27: Line 117:
 
       "registrationDate":"long long ago",
 
       "registrationDate":"long long ago",
 
       "description":"Bla"
 
       "description":"Bla"
 +
      "iswatched":"false", (false = you are not watching this user, true = you are currently watching this user)
 
     }
 
     }
  
Line 48: Line 139:
 
       "city":"Vienna",
 
       "city":"Vienna",
 
       "registrationDate":"long long ago",
 
       "registrationDate":"long long ago",
−
       "description":"Bla"
+
       "description":"Bla",
 +
      "iswatched":"false",
 
       "unreadPMCount":"12",
 
       "unreadPMCount":"12",
 
       "watchlistCount":"1234",
 
       "watchlistCount":"1234",
Line 62: Line 154:
 
       "notification_subscribedFolderCount":0,
 
       "notification_subscribedFolderCount":0,
 
       "notificationTotalCount":6
 
       "notificationTotalCount":6
 +
    }
 +
 +
== Get Submission Details ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/std/getSubmissionDetails
 +
 +
=== Parameters ===
 +
* id = numerical ID of the desired submission. Mandatory field.
 +
 +
=== Returned data ===
 +
 +
    {
 +
      "contentType":"1", (0=story, 1=art, 2=music, 3=journal, 4=photo)
 +
      "title":"Battle Sheep",
 +
      "description":"This is a description Yay!
 +
   
 +
    \nTest test
 +
   
 +
    \nblablabla",
 +
      "fileName":"Toumal - Battle Sheep.jpg",
 +
      "fileExtension":"jpg",
 +
      "width":"1024",
 +
      "height":"685",
 +
      "contentSourceUrl":"http://someurl", (URL of the full size image, if applicable)
 +
      "previewSourceUrl":"http://someurl", (URL of the 800px preview)
 +
      "thumbnailSourceUrl":"http://someurl" (URL of the thumbnail)
 +
      "isFavourite":false (only if you're OTP-authenticated correctly, else it will always be false)
 +
    }
 +
 +
== Get Shouts ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/api/getShouts
 +
 +
=== Parameters ===
 +
* id = numerical ID of the desired user. Defaults to own user if omitted
 +
 +
=== Returned data ===
 +
 +
    {
 +
      "entries":[
 +
        {
 +
          "id":"280640",
 +
          "parentID":"-1",
 +
          "username":"JayriAvieock",
 +
          "userID":"189019",
 +
          "date":"1333734740",
 +
          "message":"rawr? you called :3"
 +
        },
 +
        {
 +
          "id":"280628",
 +
          "parentID":"280623",
 +
          "username":"Toumal",
 +
          "userID":"13",
 +
          "date":"1333729895",
 +
          "message":"Yes, I'd love that!"
 +
        },
 +
        {
 +
          "id":"280623",
 +
          "parentID":"-1",
 +
          "username":"markshark",
 +
          "userID":"142337",
 +
          "date":"1333729622",
 +
          "message":"Thanks for the favorites, mr Toumal. I wonder if we could get a picture together at some point ;-)"
 +
        },
 +
        {
 +
          "id":"280542",
 +
          "parentID":"-1",
 +
          "username":"Rubberkitten",
 +
          "userID":"32931",
 +
          "date":"1333714929",
 +
          "message":"hello :3."
 +
        },
 +
        {
 +
          "id":"280381",
 +
          "parentID":"-1",
 +
          "username":"Fenndragon",
 +
          "userID":"209900",
 +
          "date":"1333670188",
 +
          "message":"thanks for the watch, and kind words!"
 +
        }
 +
      ]
 +
    }
 +
 +
== Get Comments ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/api/getComments
 +
 +
=== Parameters ===
 +
* id = numerical ID of the page of which the comments should be fetched. Mandatory field.
 +
 +
=== Returned data ===
 +
 +
    {
 +
      "entries":[
 +
        {
 +
          "id":"249324",
 +
          "parentID":"-1",
 +
          "username":"Testuser11",
 +
          "userID":"57129",
 +
          "date":"1311249060",
 +
          "message":"blablablablabla"
 +
        },
 +
        {
 +
          "id":"249325",
 +
          "parentID":"249324",
 +
          "username":"Testuser11",
 +
          "userID":"57129",
 +
          "date":"1311249060",
 +
          "message":"A reply"
 +
        }
 +
      ]
 +
    }
 +
 +
 +
== Writing a comment ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/comment/saveComment
 +
 +
=== Parameters ===
 +
* sfCommentAdditionalId = page ID of the submission this is a comment on
 +
* sfCommentReplyTo = ID of the comment to reply to, empty if a new comment
 +
* sfCommentReplyTextarea = Text message of the comment
 +
* assignme = "true"
 +
 +
=== Returned data ===
 +
 +
    {
 +
        "status":1, (0=error, 1=OK)
 +
        "message":"" (Filled with html error message if status = 0)
 +
    }
 +
 +
 +
== Writing a shout ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/comment/saveShout
 +
 +
=== Parameters ===
 +
* sfCommentAdditionalId = user ID of the user on whose profile this shout is to be posted
 +
* sfCommentReplyTo = ID of the shout to reply to, empty if a new shout
 +
* sfCommentReplyTextarea = Text message of the shout
 +
* assignme = "true"
 +
 +
=== Returned data ===
 +
 +
    {
 +
        "status":1, (0=error, 1=OK)
 +
        "message":"" (Filled with html error message if status = 0)
 +
    }
 +
 +
 +
== Fetch list of PMs ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/user/pm/list?format=json
 +
 +
=== Parameters ===
 +
* None
 +
 +
=== Returned data ===
 +
 +
    [ 
 +
        { 
 +
            "id":"6385869",
 +
            "fromUserID":"89189",
 +
            "toUserID":"13",
 +
            "fromUserName":"Someuser",
 +
            "toUserName":"Yourname",
 +
            "timestamp":"1430151997",
 +
            "subject":"SoFurry Ambassadors",
 +
            "status":"0", (0=Unread, 1=Read, 2=Replied)
 +
            "threadID":"659073"
 +
        },
 +
        { 
 +
            "id":"6380243",
 +
            "fromUserID":"292333",
 +
            "toUserID":"13",
 +
            "fromUserName":"Someotheruser",
 +
            "toUserName":"Yourname",
 +
            "timestamp":"1430076550",
 +
            "subject":"Something blabla",
 +
            "status":"2",
 +
            "threadID":"658820"
 +
        },
 +
    ...
 +
    ]
 +
 +
 +
== Get contents of a PM ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/user/pm/view?id=12345&format=json
 +
 +
=== Parameters ===
 +
* id = numerical ID of the desired PM.
 +
 +
=== Returned data ===
 +
 +
    { 
 +
        "id":"6385869",
 +
        "fromUserID":"89189",
 +
        "fromUserName":"Someuser",
 +
        "toUserID":"13",
 +
        "toUserName":"Toumal",
 +
        "timestamp":"1430151997",
 +
        "subject":"SoFurry Ambassadors",
 +
        "message":"Blah blah this is the main PM message contents",
 +
        "status":"1",
 +
        "parentID":"-1",
 +
        "folder":"inbox",
 +
        "isStar":"0", (Important PMs can be "starred")
 +
        "todoState":"0", (Unused atm)
 +
        "topParentID":"6385869", (ID of the initial PM in the conversation)
 +
        "threadID":"659073"
 +
    }
 +
 +
== Send PM ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/user/pm/new
 +
 +
=== Parameters ===
 +
* PrivateMessage[toUserName] = Your username
 +
* PrivateMessage[subject] = Subject line
 +
* PrivateMessage[message] = Actual message contents
 +
* Send = "Send Message"
 +
 +
 +
=== Returned data ===
 +
 +
None
 +
 +
 +
 +
== Reply to PM ==
 +
 +
=== Request URL ===
 +
    http://api2.sofurry.com/comment/savePM
 +
 +
=== Parameters ===
 +
* sfCommentReplyTo = ID of the PM to reply to
 +
* sfCommentReplyTextarea = Text message of the reply
 +
* assignme = "true"
 +
 +
=== Returned data ===
 +
 +
    {
 +
        "status":1, (0=error, 1=OK)
 +
        "message":"" (Filled with html error message if status = 0)
 
     }
 
     }

Latest revision as of 15:18, 14 November 2015

NOTE: The API is currently being updated. This information is subject to change fundamentally shortly.

Browse submissions

Request URL

   https://api2.sofurry.com/browse/all/art?format=json
   https://api2.sofurry.com/browse/all/stories?format=json
   https://api2.sofurry.com/browse/all/music?format=json
   https://api2.sofurry.com/browse/all/photos?format=json
   https://api2.sofurry.com/browse/all/journals?format=json

Parameters

* sortby = date, popularity, length, title, random
* from = all time, this year, this month, this week, yesterday, today
* rating = clean, adult, clean adult (max rating, leave empty to show all)

Returned data

   {
       "title": "SoFurry - All Art",
       "items": [
           {
               "thumbnail": "https://www.sofurryfiles.com/std/thumb?page=12345",
               "contentlevel": "Clean", (can be clean, adult, extreme)
               "id": "12345",
               "title": "Submission Title",
               "author": "author name",
               "link": "http://api2.sofurry.com/view/12345",
               "postTime": "1430157763",
               "tags": "Tags, separated, by, commas",
               "description": "Lengthy description"
           },
           ....
       ]
   }

Browse user submissions

Request URL

   https://api2.sofurry.com/browse/user/art?uid=1234&format=json

Parameters

* uid = optional user ID to show only this user's submissions

Returned data

Same format as regular browse request


Search submissions

Request URL

   https://api2.sofurry.com/browse/search?search=Searchterm1,Searchterm2&format=json

Parameters

* search = Search tags separated by comma. To do a fulltext search, enclose the search term with "quotation marks"
* filter = all, stories, artwork, stories, photos, journals (optional, defaults to all)
* sort = date, daterev, popularity
* daterange = all, day, week, month, 6 months, year
* minlevel = 0 (0=clean, 1=adult, 2=extreme)
* maxlevel = 2 (0=clean, 1=adult, 2=extreme)

Returned data

   {  
       "searchType":"all",
       "searchTerm":"orca",
       "items":[  
           {  
               "contentlevel":"clean",
               "id":852521,
               "tags":"Fox, Transformation, Dragon, Orca, Muscle Growth, Cock Growth, Toys, Growth, M/M, Latex, M/solo, Machines, Foot growth",
               "title":"Latex Stream Story 3: A Pleasure to Meet You",
               "author":"draconicon",
               "link":"http://www.sofurry.com/view/852521",
               "postTime":1430018009
           },
           ...
       ]
   }


Getting User Profiles

Request URL

   http://api2.sofurry.com/std/getUserProfile

Parameters

* id = numerical ID of the user whose profile you want. Optional. If omitted, the system will send your own profile data.
* username = name of the user whose profile you want. Optional. Can be used instead of id, for if you don't know the user id.

Returned data

For anyone but yourself, you get the following data: 

   {
     "username":"Toumal",
     "useralias":"toumal", (This is the url-friendly username for username.sofurry.com profile addresses)
     "userID":"13",
     "profileViewCount":"1234",
     "submissionCount":"1234",
     "submissionViewCount":"1234",
     "commentCount":"1234",
     "commentPostedCount":"1234",
     "species":"Orca",
     "gender":"1", (0=N/A, 1=Male, 2=Female, 3=Herm)
     "orientation":"0", (0=N/A, 1=Hetero, 2=Homosexual, 3=Bisexual, 4=Omnisexual)
     "mateshipStatus":"2", (0=N/A, 1=Single uninterested, 2=Single casual, 3=Single permanent, 4=Mated open, 5=Mated closed)
     "country":"Austria",
     "city":"Vienna",
     "registrationDate":"long long ago",
     "description":"Bla"
     "iswatched":"false", (false = you are not watching this user, true = you are currently watching this user)
   }

For your own user (only if you're OTP-authenticated correctly) you receive additional data about your unread PMs and notifications: 


   {
     "username":"Toumal",
     "useralias":"toumal", (This is the url-friendly username for username.sofurry.com profile addresses)
     "userID":"13",
     "profileViewCount":"1234",
     "submissionCount":"1234",
     "submissionViewCount":"1234",
     "commentCount":"1234",
     "commentPostedCount":"1234",
     "species":"Orca",
     "gender":"1", (0=N/A, 1=Male, 2=Female, 3=Herm)
     "orientation":"0", (0=N/A, 1=Hetero, 2=Homosexual, 3=Bisexual, 4=Omnisexual)
     "mateshipStatus":"2", (0=N/A, 1=Single uninterested, 2=Single casual, 3=Single permanent, 4=Mated open, 5=Mated closed)
     "country":"Austria",
     "city":"Vienna",
     "registrationDate":"long long ago",
     "description":"Bla",
     "iswatched":"false",
     "unreadPMCount":"12",
     "watchlistCount":"1234",
     "notification_voteCount":1,
     "notification_watchCount":1,
     "notification_favoriteCount":0,
     "notification_friendRequestCount":0,
     "notification_commentCount":4,
     "notification_adminCommentCount":0,
     "notification_shoutCount":0,
     "notification_forumPostCount":0,
     "notification_collaborationCount":0,
     "notification_subscribedFolderCount":0,
     "notificationTotalCount":6
   }

Get Submission Details

Request URL

   http://api2.sofurry.com/std/getSubmissionDetails

Parameters

* id = numerical ID of the desired submission. Mandatory field.

Returned data

   {
     "contentType":"1", (0=story, 1=art, 2=music, 3=journal, 4=photo)
     "title":"Battle Sheep",
     "description":"This is a description Yay!
   
   \nTest test
   
   \nblablabla",
     "fileName":"Toumal - Battle Sheep.jpg",
     "fileExtension":"jpg",
     "width":"1024",
     "height":"685",
     "contentSourceUrl":"http://someurl", (URL of the full size image, if applicable)
     "previewSourceUrl":"http://someurl", (URL of the 800px preview)
     "thumbnailSourceUrl":"http://someurl" (URL of the thumbnail)
     "isFavourite":false (only if you're OTP-authenticated correctly, else it will always be false)
   }

Get Shouts

Request URL

   http://api2.sofurry.com/api/getShouts

Parameters

* id = numerical ID of the desired user. Defaults to own user if omitted

Returned data

   {
     "entries":[
       {
         "id":"280640",
         "parentID":"-1",
         "username":"JayriAvieock",
         "userID":"189019",
         "date":"1333734740",
         "message":"rawr? you called :3"
       },
       {
         "id":"280628",
         "parentID":"280623",
         "username":"Toumal",
         "userID":"13",
         "date":"1333729895",
         "message":"Yes, I'd love that!"
       },
       {
         "id":"280623",
         "parentID":"-1",
         "username":"markshark",
         "userID":"142337",
         "date":"1333729622",
         "message":"Thanks for the favorites, mr Toumal. I wonder if we could get a picture together at some point ;-)"
       },
       {
         "id":"280542",
         "parentID":"-1",
         "username":"Rubberkitten",
         "userID":"32931",
         "date":"1333714929",
         "message":"hello :3."
       },
       {
         "id":"280381",
         "parentID":"-1",
         "username":"Fenndragon",
         "userID":"209900",
         "date":"1333670188",
         "message":"thanks for the watch, and kind words!"
       }
     ]
   }

Get Comments

Request URL

   http://api2.sofurry.com/api/getComments

Parameters

* id = numerical ID of the page of which the comments should be fetched. Mandatory field.

Returned data

   {
     "entries":[
       {
         "id":"249324",
         "parentID":"-1",
         "username":"Testuser11",
         "userID":"57129",
         "date":"1311249060",
         "message":"blablablablabla"
       },
       {
         "id":"249325",
         "parentID":"249324",
         "username":"Testuser11",
         "userID":"57129",
         "date":"1311249060",
         "message":"A reply"
       }
     ]
   }


Writing a comment

Request URL

   http://api2.sofurry.com/comment/saveComment

Parameters

* sfCommentAdditionalId = page ID of the submission this is a comment on
* sfCommentReplyTo = ID of the comment to reply to, empty if a new comment
* sfCommentReplyTextarea = Text message of the comment
* assignme = "true"

Returned data

   {
       "status":1, (0=error, 1=OK)
       "message":"" (Filled with html error message if status = 0)
   }


Writing a shout

Request URL

   http://api2.sofurry.com/comment/saveShout

Parameters

* sfCommentAdditionalId = user ID of the user on whose profile this shout is to be posted
* sfCommentReplyTo = ID of the shout to reply to, empty if a new shout
* sfCommentReplyTextarea = Text message of the shout
* assignme = "true"

Returned data

   {
       "status":1, (0=error, 1=OK)
       "message":"" (Filled with html error message if status = 0)
   }


Fetch list of PMs

Request URL

   http://api2.sofurry.com/user/pm/list?format=json

Parameters

* None

Returned data

   [  
       {  
           "id":"6385869",
           "fromUserID":"89189",
           "toUserID":"13",
           "fromUserName":"Someuser",
           "toUserName":"Yourname",
           "timestamp":"1430151997",
           "subject":"SoFurry Ambassadors",
           "status":"0", (0=Unread, 1=Read, 2=Replied)
           "threadID":"659073"
       },
       {  
           "id":"6380243",
           "fromUserID":"292333",
           "toUserID":"13",
           "fromUserName":"Someotheruser",
           "toUserName":"Yourname",
           "timestamp":"1430076550",
           "subject":"Something blabla",
           "status":"2",
           "threadID":"658820"
       },
   ...
   ]


Get contents of a PM

Request URL

   http://api2.sofurry.com/user/pm/view?id=12345&format=json

Parameters

* id = numerical ID of the desired PM.

Returned data

   {  
       "id":"6385869",
       "fromUserID":"89189",
       "fromUserName":"Someuser",
       "toUserID":"13",
       "toUserName":"Toumal",
       "timestamp":"1430151997",
       "subject":"SoFurry Ambassadors",
       "message":"Blah blah this is the main PM message contents",
       "status":"1",
       "parentID":"-1",
       "folder":"inbox",
       "isStar":"0", (Important PMs can be "starred")
       "todoState":"0", (Unused atm)
       "topParentID":"6385869", (ID of the initial PM in the conversation)
       "threadID":"659073"
   }

Send PM

Request URL

   http://api2.sofurry.com/user/pm/new

Parameters

* PrivateMessage[toUserName] = Your username
* PrivateMessage[subject] = Subject line
* PrivateMessage[message] = Actual message contents
* Send = "Send Message"


Returned data

None


Reply to PM

Request URL

   http://api2.sofurry.com/comment/savePM

Parameters

* sfCommentReplyTo = ID of the PM to reply to
* sfCommentReplyTextarea = Text message of the reply
* assignme = "true"

Returned data

   {
       "status":1, (0=error, 1=OK)
       "message":"" (Filled with html error message if status = 0)
   }
Retrieved from "http://wiki.sofurry.com/w/index.php?title=SoFurry_2.0_API&oldid=1916"