fAPI

The very simple API for Furry Art Pile

Development Basics

Dear developers

  1. Please keep resource requests down to 1-per-second-per-ip. Abusive clients will be throttled.
  2. All data is UTF-8 encoded.
  3. Data feeds are cached for 1 hour to preserve server resources. (Authenticated feeds and data resources are not cached).
  4. If you make a fun app using fAPI, let me know and I'll link you on this page.
  5. Documentation is available inside the data feeds and resources.
  6. This is a new service, pardon the Beta-ness of it all. Thanks!

URL structure

You can construct the URL to a work once you know the work id as returned by many API methods. The work URL takes the following format:

http://www.furryartpile.com/view/{work id}/

Thumbnails for works come in four different sizes: square (100px on each side), small (100px on longest side), big (150px on longest side) and preview (350px on longest side). You can construct the URL for a thumbnail once you know the thumbname and the server as returned by many API methods. The thumbnail URL takes the following format:

http://{server}/thumbs/{square|small|big|preview}/{thumbname}

You can construct the URL for a source file once you know the filename as returned by an authenticated works.xml. Please read our Hotlinking Policy before accessing source files. The source file URL takes the following format:

http://www.furryartpile.com/works/{filename}

You can construct the URL for a user icon once you know the username as returned by many API methods. If the user does not have an icon (or does not exist) a 404 error will be returned with the default user icon. The URL for user icons takes the following format:

http://www.furryartpile.com/icons/{username}.gif

Hotlinking Policy

Unless your application allows users to make comments and interact with works on FAP, please link directly to the works' page instead of the source file. Hotlinking discourages user interaction and is bad for the FAP community.

Thumbnails, user icons and other files can be used freely.

Result encoding

All information on FAP is UTF-8 encoded. Potentially unsafe HTML is double-encoded to protect FAP users without destroying the formatting of the HTML:

<a href="#" onclick="alert('XSS');">I <del>♥</del> FAP!</a>

	Becomes:

&lt;a href=&quot;#&quot; onclick=&quot;alert(&#039;XSS&#039;);&quot;&gt;I <del>&hearts;</del> FAP!&lt;/a&gt;

A full list of allowed HTML is available in the help section.

Authentication

Authentication is required to access private data feeds and access data resources as a FAP user. Initiating an authenticated session is a simple 3-step process:

  1. Get frob

    The frob is a unique, 16-bit key that says the user has authorized you to access their account. Simply send the user to this URL:

    http://api.furryartpile.com/auth/{your developer key}

    Depending on your key settings, the user will either be redirected to a passback URL or given the frob to copy and paste into your application.

  2. Get token

    After retrieving a frob from the user, you can request a token, authenticate and initiate a user session with auth.getToken.xml:

    http://api.furryartpile.com/auth.getToken.xml?key={your developer key}&frob={user frob}

    If the user has granted access to your key, a unique, 32-bit token will be returned with the privlages your key is permitted.

  3. Use/validate token

    Once you have a token and a frob, you can access private data feeds and resources with this URL structure:

    http://api.furryartpile.com/settings.xml?token={your token}&frob={user frob}
    http://api.furryartpile.com/work.submit.xml?token={your token}&frob={user frob}

    You can validate a token and check privlages with auth.checkToken.xml:

    http://www.furryartpile.com/api/auth.checkToken.xml?token={your token}&frob={user frob}

Caveats

Always encode your queries

The specification for URLs (RFC 1738, Dec. '94) poses a problem, in that it limits the use of allowed characters in URLs to only a limited subset of the US-ASCII character set. You should always encode queries when using GET or you might run into some un-expected results:

works.xml?tags=+type:art +user:ekigyuu should return works by ekigyuu that are of type:art, but the + symbol is considered a space by RFC 1738.
works.xml?tags=%2Btype:art %2Buser:ekigyuu is the proper encoded query string.

Here is a list of common symbols that should be encoded when sent to FAP:

ASCII UTF-8
+ %2B
" %22
< %3C
> %3E
~ %7E

Data Feeds

These API methods contain read-only, public data and do not require authentication to use. Documentation is available inside the data feeds.

  • works.xml

    Returns a list of works matching some critera.

  • users.xml

    Returns a list of users matching some critera.

  • tags.xml

    Returns a list of tags matching some critera.

  • comments.xml

    Returns a thread of comments matching some critera.

  • blogs.xml (currently unavailable)

    Returns a list of blogs matching some critera.

  • piles.xml (currently unavailable)

    Returns a list of piles matching some critera.

Private Data Feeds

These API methods contain read-only, private data and require authentication to use. Documentation is available inside the data feeds.

  • settings.xml (currently unavailable)

    Returns settings for an authenticated user.

  • watchlist.xml (currently unavailable)

    Returns watchlist for an authenticated user.

  • messages.xml (currently unavailable)

    Returns messages for an authenticated user.

Data Resources

These API methods Create, Update and Delete data on FAP and require authentication to use. Documentation is available inside the data resources.