This tutorial guides you through your first steps with the dive.io REST API.

Preparations

To access the API, you need an active dive.io account. Go here to create one if you haven't yet. The API requires Basic Authentication. A client for creating POST, PUT and DELETE HTTP requests (such as cURL, or the Poster firefox add-on) are handy for manual testing. You can still perform some API operations without those tools.

The tutorial assumes that you have posted a few dive log entries already via the normal web interface. Alternatively, you can start with the "Add a dive" step below.

Your first request: Fetching account data

Open the following link, and authenticate with the email address and password of your dive.io account:

https://api.dive.io/v1/self.xml

You should get a document containing your account data in XML format, similar to the example below. If you prefer a JSON-formatted response, replace ".xml" with ".json" in the address above.

<?xml version="1.0" encoding="UTF-8"?>
<DiveIo>
  <Diver>
    <Id>4</Id>
    <Firstname>John</Firstname>
    <Lastname>Deepdiver</Lastname>
    <EmailConfirmed>info@dive.io</EmailConfirmed>
    <PicHash>1e9582e7ff47d8666</PicHash>
    <Created>2011-03-17 10:40:39.409262+01</Created>
    <Modified>2011-03-31 11:44:45.680179+02</Modified>
  </Diver>
</DiveIo>

More details: "Diver" resource and "Diver" object attributes

List all dives

The following address lists all dives that are currently in the logbook:

https://api.dive.io/v1/self/dives.xml

This should (assuming that there are already dive records in your logbook) return something similar to the following example:

<?xml version="1.0" encoding="UTF-8"?>
<DiveIo>
  <Dives>
    <Dive>
      <Id>42</Id>
      <DiveDate>2010-09-16</DiveDate>
      <InTime>10:28:00</InTime>
      <Duration>00:39:50</Duration>
      <MaxDepth>20.7</MaxDepth>
      <DiverId>4</DiverId>
      <DiveNumber>28</DiveNumber>
    </Dive>
    <Dive>
      <Id>56</Id>
      <DiveDate>2010-09-18</DiveDate>
      <InTime>14:33:00</InTime>
      <Duration>00:40:30</Duration>
      <MaxDepth>33</MaxDepth>
      <DiverId>4</DiverId>
      <DiveNumber>29</DiveNumber>
    </Dive>
  </Dives>
  <Status>200 OK</Status>
</DiveIo>

The dive logbook of the example user contains two dive logs. To receive the same data in JSON format, replace ".xml" with ".json" in the link above. More details about this API resource is available here.

Fetch a Dive

Each of the "Dive" records on the dive list from the link above contains an "Id" field (42 and 56, respectively). Replace the '<Id>' in the following link with one of these Id's from your own response to fetch the full record of the respective dive (in XML):

https://api.dive.io/v1/dives/<Id>.xml

More details about this API resource can be found here.

Add new Dives

Copy the following XML data into a file (for example, named "newdive.xml"):

<?xml version="1.0" encoding="UTF-8"?>
<DiveIo> 
  <Dives>
    <Dive>
      <DiveDate>2010-09-18</DiveDate>
      <InTime>14:33:00</InTime>
      <Duration>00:40:30</Duration>
      <MaxDepth>33</MaxDepth>
    </Dive>
  </Dives>
</DiveIo>

Use a web client that can POST this file as file upload (named "xml") to the server. With cURL, the respective command line is:

curl -u <user>:<password> -X POST -F "xml=@newdive.xml" \
https://api.dive.io/v1/dives.xml

The response from the API server should confirm that the dive has been added to the log book.

The example above list only the minimum set of required fields for a dive log entry. More fields, including depth and pressure samples, can be included when creating a log entry - see the full documentation of the Dive object.

Delete a dive

To delete a dive, take the dive's "Id" field, and perform a DELETE HTTP request on the following URL (replacing <Id> with the respective Id of the dive to be deleted:

DELETE https://api.dive.io/v1/dives/<Id>.xml

For example, the cURL command line is:

curl -u <user>:<password> -X DELETE \
https://api.dive.io/v1/dives/<Id>.xml