4thefile_api_reference
Differences
This shows you the differences between two versions of the page.
|
4thefile_api_reference [2010/11/04 23:15] jay |
4thefile_api_reference [2011/01/04 22:19] (current) jay |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Introduction ===== | ===== Introduction ===== | ||
| - | The 4theFile API is a REST-style API that uses simple standard technologies: HTTP requests with Basic auth, and XML or JSON response content. The API is designed primarily to allow developers and maintainers of web applications to easily provide an email interface to their applications without all the hassles involved in running an email server and parsing complex multi-part email messages, possibly with inline images, html, and attachments -- 4theFile takes care of all that for you. | + | The 4theFile API is a REST-style API that uses simple standard technologies: HTTP requests with Basic auth, and XML or JSON response content. The API is designed primarily to allow developers and maintainers of web applications to easily provide an email interface to their applications and integrate the list of submitted emails into their application's interface -- without all the hassles involved in running an email server and parsing complex multi-part email messages, possibly with inline images, html, and attachments. 4theFile takes care of all the messy stuff for you. |
| For more information, see the [[4theFile API | 4theFile API Overview]] | For more information, see the [[4theFile API | 4theFile API Overview]] | ||
| ===== Using the API ===== | ===== Using the API ===== | ||
| + | |||
| + | * Terminology: "Resources" vs "resources". In 4theFile, we call the linkable web pages we make out of submitted emails "4theFile Resources". When talking about REST API's, it's customary to call everything that has a URL a "resource". In this document we try to use a capital R when talking about 4theFile Resources and lowercase r when talking about the various things we can access through the API (some of which are Resources... and some aren't). OK? | ||
| * A complete request includes an HTTP method, a url formed from the "endpoint", the "resource", and a response format specifier, and maybe some optional query parameters. PUT and POST methods may also require some input data in the request content body. The default endpoint is https://4thefile.com/api_v1 | * A complete request includes an HTTP method, a url formed from the "endpoint", the "resource", and a response format specifier, and maybe some optional query parameters. PUT and POST methods may also require some input data in the request content body. The default endpoint is https://4thefile.com/api_v1 | ||
| Line 13: | Line 15: | ||
| <method> <endpoint><resource>.<format>[?<querystring>] | <method> <endpoint><resource>.<format>[?<querystring>] | ||
| - | Example: to GET the list of 4theFile Resources in Collection HJf56 that have "tag" 99 in XML format, the API resource is /collections/HJf56 and the whole request would look like: | + | Example: to GET the list of 4theFile Resources in Collection HJf56 that have "tag" 99 in XML format, the API resource is /collections/HJf56/resources and the whole request would look like: |
| - | GET https://4thefile.com/api_v1/collections/HJf56.xml?tag=99 | + | GET https://4thefile.com/api_v1/collections/HJf56/resources.xml?tag=99 |
| - | * Each request must be authenticated with your username and apiKey (used as the Basic auth password). Most http clients and client libraries have support for Basic auth, so you don't need to be concerned with the details of the HTTP headers. For example, when using the Curl command line client you only need to add the -u option //curl -u user:apiKey// | + | * Each request must be authenticated with your username and apiKey (used as the Basic auth password). If you don't have an apiKey yet, please [[tech_support_contacts | contact our support team]]. Most http clients and client libraries have support for Basic auth, so you don't need to be concerned with the details of the HTTP headers. For example, when using the Curl command line client you only need to add the -u option //curl -u user:apiKey// |
| * If your request is successful, you'll receive an HTTP "success" response code (usually 200 unless otherwise noted in the documentation for the resource) and the content in the format you specified (with appropriate MIME type, text/xml or application/json). | * If your request is successful, you'll receive an HTTP "success" response code (usually 200 unless otherwise noted in the documentation for the resource) and the content in the format you specified (with appropriate MIME type, text/xml or application/json). | ||
| Line 25: | Line 27: | ||
| * If the GET method is supported for a resource, HEAD is also supported | * If the GET method is supported for a resource, HEAD is also supported | ||
| - | ===== Resources ===== | + | ===== API Resources ===== |
| - | In all resource URLs below, segments that begin with : such as :collectionkey are placeholders, and you should substitute a valid collection key or resource key. | + | In all resource URLs below, segments that begin with : such as :collectionkey are placeholders, and you should substitute a valid Collection key or Resource key. |
| In each resource description we've provided a Curl command line which may be useful for exploring or testing the API. For actual integration with your application you'll probably want to use a language-specific HTTP library (such as libCurl, or LWP for perl). For more info on Curl and libCurl http://en.wikipedia.org/wiki/CURL | In each resource description we've provided a Curl command line which may be useful for exploring or testing the API. For actual integration with your application you'll probably want to use a language-specific HTTP library (such as libCurl, or LWP for perl). For more info on Curl and libCurl http://en.wikipedia.org/wiki/CURL | ||
| + | |||
| + | We've shown most example responses in XML, but currently all responses are also available as JSON. An example .json response is shown on the first example page for ([[get_collections | GET /collections]]) | ||
| ==== /collections ==== | ==== /collections ==== | ||
| - | GET /collections.format returns the list of collections owned by authenticated account | + | GET /collections.format returns the list of Collections owned by authenticated account |
| * response formats supported: .xml, .json | * response formats supported: .xml, .json | ||
| Line 41: | Line 45: | ||
| ==== /collections/:collectionkey ==== | ==== /collections/:collectionkey ==== | ||
| - | GET /collections/:collectionkey.format returns the collection details | + | GET /collections/:collectionkey.format returns the Collection details |
| * response formats supported: .xml, .json | * response formats supported: .xml, .json | ||
| * query parameters: none | * query parameters: none | ||
| Line 48: | Line 52: | ||
| ==== /collections/:collectionkey/resources ==== | ==== /collections/:collectionkey/resources ==== | ||
| - | GET /collections/:collectionkey/resources.format returns the list of resources in collection :collectionkey | + | GET /collections/:collectionkey/resources.format returns the list of Resources in Collection :collectionkey |
| * response formats supported: .xml, .json | * response formats supported: .xml, .json | ||
| - | * query parameters: per_page (optional - max resources to return at once, default 30), page (optional, default 1) | + | * query parameters: |
| + | * per_page (optional - max resources to return at once, default 30) | ||
| + | * page (optional, default 1) | ||
| + | * tag (optional - only Resources with matching tag will be returned. the special tag "untagged" will return all Resources in the Collection that don't have any tags) | ||
| + | * cdate (optional - only resources with collection_id or tags modified since cdate will be returned. cdate must be in yyyy-mm-dd or "yyyy-mm-dd hh:mm:ss" format) | ||
| * [[get_collection_resources | details and example]] | * [[get_collection_resources | details and example]] | ||
| Line 56: | Line 64: | ||
| ==== /resources ==== | ==== /resources ==== | ||
| - | GET /resources.format returns the list of resources owned by the authenticated account | + | GET /resources.format returns the list of Resources owned by the authenticated account |
| * response formats supported: .xml, .json | * response formats supported: .xml, .json | ||
| * query parameters: per_page (optional - max resources to return at once, default 30), page (optional, default 1) | * query parameters: per_page (optional - max resources to return at once, default 30), page (optional, default 1) | ||
| - | * [[get_resources | details and example]] | + | * the response format is identical to that returned for [[get_collection_resources | /collections/:collectionkey/resources]]. see above. |
| ==== /resources/:resourcekey ==== | ==== /resources/:resourcekey ==== | ||
| - | GET /resources/:resourcekey.format returns the details for resource :resourcekey, including the public http and https urls that can be used to make clickable links in a web interface | + | GET /resources/:resourcekey.format returns the details for Resource :resourcekey, including the public http and https urls that can be used to make clickable links in a web interface |
| * response formats supported: .xml, .json | * response formats supported: .xml, .json | ||
| * [[get_resource_details | details and example]] | * [[get_resource_details | details and example]] | ||
| + | ==== /resources/:resourcekey/attachments ==== | ||
| + | |||
| + | GET /resources/:resourcekey/attachments.format returns a list of direct links to any attachments in the top-level message for | ||
| + | :resource, plus some meta data. this could be useful in a specialized collection where, for example, the 1st attachment is known to always include a scanned image of a purchase receipt. | ||
| + | * response formats supported: .xml, .json | ||
| + | * [[resource_attachment_list | details and example]] | ||
| ==== /collections/:collectionkey/resources/:resourcekey ==== | ==== /collections/:collectionkey/resources/:resourcekey ==== | ||
| + | GET /collections/:collectionkey/resources/:resourcekey.format returns resource :resourcekey in format identical to [[get_resource_details | /resources/:resourcekey]] but ONLY if Resource is in Collection :collectionkey | ||
| + | |||
| + | PUT or POST /collections/:collectionkey/resources/:resourcekey.format assigns Resource :resourcekey to Collection :collectionkey and/or updates the Resource tags. | ||
| + | * response formats supported: .xml, .json | ||
| + | * request content body format (optional): form-encoded key/value pair; e.g. tags=tag1,tag2 | ||
| + | * [[put_collection_resource | details and example]] | ||
| + | DELETE /collections/:collectionkey/resources/:resourcekey.format removes the Resource from the Collection provided that you own the Resource. It does not delete the Resource from 4theFile. | ||
| + | * response formats: .xml, .json | ||
| + | * [[del_collection_resource | details and example]] | ||
4thefile_api_reference.1288912527.txt.gz · Last modified: 2010/11/04 23:15 by jay