The 4theFile API
- Perl Client Library reference implementation
The 4theFile API
This is an old revision of the document!
The 4theFile API provides RESTful web services for use in integrating 4theFile with other web-based applications. The API has the following features:
The Problem:
You've developed a project management database. It includes an interface for adding notes or uploading attachments for each project. But you've realized that often the content for these notes come in the form of email, and cutting and pasting those emails into your notes text area isn't very effective or satisfying. So you'd like a better way to associate these emails with a the right project records.
The Solution:
This simple example required one (count 'em, one!) API call, a simple HTTP GET to a url that looks something like this:
https://4thefile.com/api_v1/collections/XyzProjects/resources?tag=235
and a few more lines of code to parse out the relevant fields from the 4theFile resource objects in the response and display them with clickable links in your application.
https://4theFile.com/api_v1/collections/<collectionkey>/resources.xml
Authentication is performed via Basic authentication, an HTTP standard that's been around for a long time. Basic auth is not very secure when performed over an unencrytped connection, since anyone snooping on the wire can read the username and passord (“credentials”) in the HTTP headers. However, Basic auth is quite secure under 3 conditions:
These conditions are met when using the 4theFile API over the https endpoint, so Basic is an appropriate and secure authentication method.
Q: Why did Twitter decide Basic auth wasn't secure enough?
A: The Twitter API was designed to solve a different type of problem than the 4theFile API. Third-party sites that use the Twitter API (such as TwitPic.com, for example) usually need access to an individual end user's Twitter data. When you used the original version of TwitPic, they'd ask you for your Twitter password and then they would use that password to post your pictures to your Twitter account via the API. Not to pick on TwitPic, but the risk here is that now you need to trust both Twitter AND TwitPic to protect your Twitter credentials. As the number of 3rd party sites that use the Twitter API grew, this situation got out of control, and a new solution was needed. The delegated API authorization approach called OAuth was designed for this precise scenario, and OAuth is now the only auth scheme supported by the Twitter API.
The 4theFile API, in contrast, is designed to access data that belongs to the 3rd party site (the “API client”), not data that belongs to that site's users. The API client site has its own 4theFile account and its own credentials, and doesn't need to access any other 4theFile users' data. In fact there is no need for the API client site's users to register on 4theFile at all.
Undoubtedly there are uses of the 4theFile API we haven't thought of. If there's a need, we'll support OAuth in the future. If you are an application developer or maintainer and have an idea for using the API to access 4theFile end-user accounts, please let us know. Please do NOT ask your users to give you their 4theFile passwords!