4theFile Support Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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

===== Example Usage =====

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:
  - 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 figure out what to do next
  - make your killer app even more killer with 4theFile integration!

===== Authentication =====
4theFile Support Wiki

User Tools

Site Tools

Page Tools
