°C/bar/m change

dive.io in Deutsch

dive.io API documentation (Version 1)

New here? Read the Tutorial first to get started.

Note: API documentation is currently availably in English only - sorry!

The dive.io API

 Start

 Tutorial

 Overview

API Basics

 Authentication

 Content types

 Compression

API resources

 /self

 /self/dives

 /self/photos

 /dives/<id>

 /photos/<id>

Objects

 Diver (User)

 Dive (concise)

 Dive (full)

 Photo

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):

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:

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").