Helipad XML API documentation

h2. Overview

The Helipad API is XML over HTTP.  Set the following headers to inform Helipad you want to use XML:

<pre>
Accept: application/xml
Content-Type: application/xml
</pre>

It's safe to use both http://helipadapp.com and http://pad.helicoid.net.

h2. Client implementor tips

* Use CDATA to escape all text fields, like tags, title and source.  Users may include non-valid XML in these fields.
* Please read our blog about updates and changes to the API.
* Please make it clear that customers should contact you for support and not us.  We may ignore third-party client support requests.

h2. Methods

h3. Authenticate

Your application could use this to check the authentication details are correct:

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
"http://pad.helicoid.net/authenticate?email=alex@example.com&password=test"
</pre>

h3. Get all documents

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
</request>' \
http://pad.helicoid.net/documents
</pre>

h3. Get all document IDs

This is a relatively fast method that can be called when syncing with Helipad.  Call a get request on <code>/document/all_ids</code>.

h3. Documents changed since date

You can send <code>changed_since</code> with an integer date (number of seconds since 1970) to limit the list of documents to ones that have changed.  This is used by our iPhone app to reduce the amount of traffic for syncing.  Example:

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
  <changed_since>123456789</changed_since>
</request>' \
http://pad.helicoid.net/documents
</pre>

h3. Get a list of document titles

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
</request>' \
http://pad.helicoid.net/documents/titles
</pre>

h3. Get one document

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
</request>' \
http://pad.helicoid.net/document/1/get
</pre>

h3. Get the document's html

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
</request>' \
http://pad.helicoid.net/document/1/format/html
</pre>

h3. Search for a document

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
  <search>test</search>
</request>' \
http://pad.helicoid.net/document/search
</pre>

h3. Show documents tagged with

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
</request>' \
http://pad.helicoid.net/document/tag/test
</pre>

Response: A set of documents with the root tag of 'documents'.

h3. Defining tags in XML

Tags can be specified as a space separated list:

<pre>
<tags>test helipad</tags>
</pre>

h3. Update document

You can omit fields if you want to keep them the same.

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
  <document>
      <title>Test document</title>
      <source>This is a test</source>
      <tags>
        testtag testtag2
      </tags>
  </document>
</request>' \
http://pad.helicoid.net/document/1/update
</pre>

Response: <pre><saved>true</saved></pre>

h3. Create document

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
  <document>
      <title>New document</title>
      <source>This is a test</source>
      <tags>
        testtag testtag2
      </tags>
  </document>
</request>' \
http://pad.helicoid.net/document/create
</pre>

Response: <pre><saved>true</saved></pre>

h3. Destroy document

<pre>
curl  -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '
<request>
  <authentication>
    <email>alex@example.com</email>
    <password>test</password>
  </authentication>
</request>' \
http://pad.helicoid.net/document/2/destroy
</pre>

Response: <pre><deleted>true</deleted></pre>