API Documentation

This document describes the API methods available for consumption by third-party developers, plus some technical information that may be of interest to anyone. Please notice that the API is not final (you can use the method /version to check the current version) and should be considered as experimental.

Overview

This API is in beta trial and is limited to a very small set of methods. This documentation also is very limited and assumes the developer has the know-how necessary to use it straightforward. If it is not the case, additional information (see Other sites with useful resources and information) might be necessary. Some methods are open to everyone and others require authentication by means of the OAuth protocol, in which case there are some pre-requisites:

  1. An API key (apply for a new one | your API keys)
  2. A token of the user using your program

Times are given in the GMT standard timezone (no Daylight saving).

Feed information

The user feed is a valuable element that is available for everyone. Typically you can retrieve the same information by using the API methods /people/info and /files/list, but in your use may make more sense to consume the feed (XML based RSS 2.0). Use the following address model to get a user feed: http://www.plifk.com/(username)/feed

Avatar images

The link for the avatar images are constructed in the following way:
http://uimg.plifk.com/(user id)-(icon secret)(size end).jpg

The icon secret can be retrieve by means of the /people/info method. By "size end" we mean the URI termination for the wanted size. They are: "-t" for thumbnail, "-s" for square, "-m" for small, "" (nothing) for medium and "-b" for large.

Download links

The dataurl element in the /files/info response is the download link for a given object (file).

This value can be cached, but can change at anytime as well as filename and download_secret can. If the file is not found you at the value of dataurl you should refresh the value before assuming anything (such as that the file is not available anymore). Please notice that secret and download_secret are two distinct and independent params.

Appending ?torrent to the end of the link you can get a .torrent for the file, which can be useful for the download of large files.

Don't rely on the http://storage.plifk.com/(username)/(file_id)-(download_secret)/(filename) pattern.
This is a pattern found at the dataurl element. You should not take it for granted. Instead, always use the dataurl value. Failure to comply with this will break your application sometime.

How to link

Avoid linking with a / (trailing slash) at the end or without the initial www. at the beginning. If you do so the user will receive a permanent redirection request to the right address, degrading the user experience.

We provide short links at the domain plifk.li and the following redirections are available:

base58_file_id is the file_id after being transformed to base58 (reference at the not-related Flickr web service). The shorturl element of the /files/info method response has this link ready-to-use.

Request format

This is a HTTP REST based API. The API server is in http://api.plifk.com/ and to call a simple GET method you should build a URI such as the following:

http://api.plifk.com/files/list?user_id=1&page=3

where /files/list is the method intended and the user_id and page are the request parameters used in this query.

You must know that method and method/ (notice the slash) are not considered the same for the sake of consistency and calls to something like /files/list/ will not work.

Response formats and encoding

We use and assume that all transactions are made with the utf-8 encoding. Don't send requests encoded in nothing else.

Except for the /oauth/* methods, all other methods have two response formats. They are: xml and json.

Both provide the same information. The json can be handful if you use Javascript and the XML is easer for human reading and perhaps parsing too.

This may be given as the responseformat param. Possible values: xml (default), json.

All response values must be considered as of a string type, regardless of their true nature, except for the pagination element.

Error responses

For now what we basically send two errors information. One (404) for when the resource (method or user) is not found. Another (500) for bad requests, that is triggered when a condition is not satisfied or in case of a server errors.
We will introduce a more useful (and backwards compatible) error response soon. The structure of the error information can be seen by accessing a method (except the ones that start with /oauth*, that have their own way to deal with it) without giving the required params (example) or by accessing a method or resource that does not exists (example).

Other sites with useful resources and information

Tip: if you ever consumed Twitter's API in any way you will see that this is much like it.

Methods currently available

Public ones

/test/echo

Sends a response echoing the user request (example).
HTTP Method(s): GET
Response example

/version

Sends a response with the current version of the API. Even numbers identify a version as stable, odd number as experimental and "a" is for alpha, "b" is for beta.
HTTP Method(s): GET
Response example

/people/info

Get user information. Note that users can hide their e-mails from public search and this method will return not found in this case, even if there is an account for the given e-mail.
HTTP Method(s): GET
Parameters: one of the following is required: user_id, username, email.
Response example

/tags/user_list

List of all tags used by the given user.
HTTP Method(s): GET
Parameters: user_id (required)
Response example

/files/info

Get information about a file.
HTTP Method(s): GET
Parameters: file_id (required)
Response example

/files/list

List the files of a given user.
HTTP Method(s): GET
Parameters: user_id (required), per_page (optional, default: 20), page (optional, default: 1)
Response example

Authentication (OAuth)

/oauth/request_token

Allows a Consumer application to obtain an OAuth Request Token to request user authorization. This method fulfills Secion 6.1 of the OAuth 1.0 authentication flow.
HTTP Method(s): GET
Format: OAuth HTTP Authorization Scheme
Parameters: See Section 6 Of the OAuth Core Specification for required parameters

With this method you will obtain some token data. You should create an URI to http://plifk.com/api/authorize with the oauth_token data from the oauth/requesttoken method appended to the the right end of this URI. As in: http://example.com/api/requesttoken?oauth_token=6c0e40771d0db03a5ebfb67df9080703 (don't forget the ?) and store the token secret to use to request an access token after the user authorizes.

/oauth/access_token

Allows a Consumer application to exchange the OAuth Request Token for an OAuth Access Token. This method fulfills Secion 6.3 of the OAuth 1.0 authentication flow.
HTTP Method(s): POST
Format: OAuth HTTP Authorization Scheme
Parameters: OAuth HTTP Authorization Scheme

Authentication required methods

You have to sign every method call that requires authentication as dictated by the OAuth documentation.

/activity/recent

Shows recent activity from contacts (right now only the files uploaded).
HTTP Method(s): GET

/upload/status

Get user upload status information showing how much bandwidth is used, left, etc.
HTTP Method(s): GET

Methods yet to be released

As of February 17th, 2010 these methods are almost certainly functioning correctly but were not implemented because of lack of testing against failure. They might be released at any time.

Authentication required methods

/upload

Upload a file.
HTTP Method(s): POST (PUT might be added in the future with the expected slightly different behaviour)
Parameters: file (required), title (optional, up to 100 chars), short (optional, up to 120 chars), description (optional, up to 4096 chars)

/files/setmeta

Set the metadata for a file (note that everything is required).
HTTP Method(s): POST
Parameters: file_id (required), title (required, up to 100 chars), short (required, up to 120 chars), description (required, up to 4096 chars, including HTML mark-up), filename (required, up to 30 chars)
Response: empty on success.


Last modified: February 17th, 2010