dive.io API documentation (Version 1)

Overview

The dive.io API (Application Programming Interface) allows desktop applications and other websites to access dive.io data storage. The API is a HTTP-based REST API, and provides data in JSON and XML (HTML is also provided "as is" for the read-only methods, but not recommended since its format might change).

The Base URI for the API is https://api.dive.io/v1

Authentication

Currently, all API methods require authenticating with an valid, active dive.io account. The authentication method supported is Basic Authentication, using the (confirmed) email address of an account as the username. We're looking into other authentication schemes, most likely we'll add OAuth support at some point in time.

Content types

As described above, the API provides the following formats (content types):

• JSON (MIME-Type: 'application/json', Extension '.json')
• XML (MIME-Type: 'application/xml', Extension '.xml')

Note: Some level of HTML support is also provided, but not recommended for production! Only use it for debugging and testing, since it does not support all resources/methods, and contains bugs.

Specific response Content Types can be requested from the API server in two different ways: Either by including the respective Accept: HTTP header in the request (and relying on HTTP content type negotiation), or by appending the extension (as listed above) to the URI. Extensions override content negotiation, and the default response format is XML.

XML responses/requests are all wrapped in a <DiveIo> Tag (content objects are explained below) - an example of a request/response frame is:

   <?xml version="1.0" encoding="UTF-8"?>
     <DiveIo>
       ... (content objects) ...
     </DiveIo>

Content Type examples:

• Using Accept: application/json,application/xml;0.9 as HTTP header in the request will return the API response in JSON format.
• Appending .xml to the URI of a API request will make the API reserver respond in XML format (and override any Accept:-based content type negotiation).

Response Compression

The API server supports HTTP response compression, and its use is strongly recommended. Compression can be requested from the server setting the "Accept-Encoding" header to the desired compression method. The server provides compression methods according to the Apache docmentation. Use of "gzip" is recommended.

Request Compression

The server supports gzip compressed data when processing PUT requests and "multipart/formdata" POST requests (aka "file uploads"). Compressing larger requests is strongly recommended. The ".gz" file ending is not required when posting compressed files - compressed data will be auto-detected.

Request compression is not supported for "application/x-www-form-urlencoded" POSTs (aka "form posts").