====== The 4theFile API Overview ======

The 4theFile API provides RESTful web services for use in integrating 4theFile with other web-based applications. The API has the following features:

  * all communication via HTTP or HTTPS
  * authentication via HTTP Basic auth
  * easy to understand and learn
  * easy to call from any modern programming language
    * fully working sample implementation of a perl client library available, with source code and tests
  * choice of XML or JSON response objects. more representations (e.g. jsonp) may be supported in the future

The [[4thefile_api_reference]] includes documentation and examples of all API resources.

===== Synopsis =====

  - A 4theFile Collection provides a custom email address for submitting emails to a functional area of your site. The Collection is owned and controlled by you, and there's no need for your users to become registered 4theFile users.
  - The 4theFile API allows you to integrate the list of emails submitted to the Collection into your site's interface, while avoiding all the messy issues usually associated with email integration.

===== Example Use Case =====

**The Problem:** 

You've developed a project management system called XyzProjects.com. 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 convenient. So you'd like a better way to associate these emails with a the right project records. 

**The Solution:**
  - Register on 4theFile.com and set up a collection called "XyzProjects" with custom email address //xyzprojects@4thefile.com//. 
  - On the detail page for project #235 in your application, provide a mailto: link and instruct users to forward relevant emails to //xyzprojects+235@4thefile.com//. The "+235" part of the email address is called a "tag" in 4theFile.
  - In the application code that generates the detail page, 
    - use the 4theFile API to retrieve the list of 4theFile resources for collection XyzProjects that have tag 235. The response will be a chunk of XML or JSON that describes the list of 4theFile resources that match. The response will NOT include the content of the emails in the collection, but rather the "meta data" such as the subject, the From address, etc., as well as an http or https link to the full resource content on 4theFile.
    - Parse the response and use the contents to present the user with a clickable list of the resource descriptions for emails relevant to your project.

This simple example required one (count 'em, one!) API call, a simple HTTP GET to a url that looks something like this: 
<code>https://4thefile.com/api_v1/collections/XyzProjects/resources?tag=235</code>
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.

===== How to Get Started =====

  - register on 4theFile
  - request an API key from [[tech_support_contacts|4theFile support]]
  - set up a collection in your 4theFile account, and get the email address and collectionkey for your collection
  - get an HTTP client library for your language of choice. It needs to support Basic auth (required) and SSL (recommended). Most do. You could even start with a command-line client like Curl (available on all platforms) or lwp-request (linux)
  - Make a test GET to <code>https://4theFile.com/api_v1/collections/<collectionkey>/resources.xml</code> 
    * use your 4theFile account username for the Basic auth username, and your 4theFile apiKey (NOT your 4theFile login password) for the Basic auth password. You should get back a status code of 200 and a chunk of XML content (if everything is good), or a non-200 status code and an explanation in the content if there's a problem.
  - go read the [[4theFile API Reference]] to learn what else you can do with the API

===== Authentication =====

Authentication is performed via "Basic" authentication, an HTTP standard that's been around for a long time and is well supported in HTTP client sofware. Basic is an effective and secure authentication mechanism under 3 conditions:
  - The HTTP headers are encrypted (this is always true when using SSL/TLS encryption as is the case for https URLs)
  - The user never needs to share account credentials with a 3rd party service
  - There is no need for "session management" functions such as inactivity logout.
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. In a nutshell, OAuth requires the end users to log in to their Twitter account and approve a request for access to their data by the 3rd party API. OAuth includes a clever mechanism for making this transaction fairly transparent to the end user.

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. Since only the API client must be authenticated by 4theFile, Basic auth is suitable authentication solution, and in fact OAuth would not be a good fit.

Undoubtedly there are uses of the 4theFile API we haven't thought of. If there's a need for delegated authorization for access to data not owned by the API client account, 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 data, please let us know. //Please do NOT ask your users to give you their 4theFile passwords or apiKeys!//

===== Use with AJAX =====

If your web application's interface uses AJAX, you might be thinking that you can call the 4theFile API to get a 4theFile resource list in json format directly from inside the browser via XMLHttpRequest. There are 2 reasons why this isn't a good idea:
  - your browser probably won't allow it, because you're violating the "same origin" policy that helps prevent malicious cross-site scripting (XSS) attacks
  - you would need to provide access to your API credentials in the client-side javascript, thereby exposing them in the client-side source code

So, you'll need to provide your own ajax callback that in turn calls the 4theFile API from the server, or else provide a web proxy in the same origin as your server as described here http://developer.yahoo.com/javascript/howto-proxy.html

Note: If you've read this far, you may be familiar with JSONP (an alternate solution to cross-domain ajax problems). We'd probably be willing to support JSONP as an alternative response format in the future if there's any demand for it. So if you'd like JSONP, [[tech_support_contacts | let us know]].