API Resource /self/dives

This resource reflects the list of all dive log entries posted by the authenticated user. This resource supports listing and adding dives, depending on the HTTP method used.

Resource URI

https://api.dive.io/v1/self/dives (.xml/.json/.html)

Supported Methods

GET (index), PUT (create), POST (create), OPTIONS

GET /self/dives (index)

Description

Provides a concise list of all dive records in a user's logbook

Authentication

Required. Shows dives by the authenticated user only

Request structure

n/a (empty)

Response structure

Returns a list of concise Dive objects, wrapped in a "Dives" tag/hash (or an empty list if user hasn't posted any dive log entries)

Response Example (JSON):

  {"Dives": 
    [
      { 
        "Id":"56",
        "DiveDate":"2010-09-18",
        "InTime":"14:33:00",
        "Duration":"00:40:30",
        "MaxDepth":"33",
        "DiverId":"4",
        "DiveNumber":29
      },
      {
        "Id":"42",
        "DiveDate":"2010-09-16",
        "InTime":"10:28:00",
        "Duration":"00:39:50",
        "MaxDepth":"20.7",
        "DiverId":"4",
        "DiveNumber":28
      }
    ],
   "Status": "200 OK"
  }

Response Example (XML)

<?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>29</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>

PUT /self/dives (create)

Description

Adds dive log entries to the user's log book. Note that for clients that do not support PUT, identical functionality is also available over POST (see below).

Authentication

Required

Request structure

The file to be sent in the PUT request must be a list of Dive objects, wrapped in "Dives" tag/hash, either in XML or JSON format (see example below). It is recommended that larger Divelists are to be gzipped before the are being sent to the server. The server auto-detects format as well as compression.

Response structure

Returns information about dives that have been added, and such that have been ignored (duplicates). For an example response, see below.

Request Example (XML)

The following example shows the minimum contents of a file to be uploaded (for two dives). Only the minimum set of required fields is included in the example (and neither Samples nor Buddies) - a description of all available fields is contained in the Dive object description

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

Response example (XML)

The following response to the request above shows that one dive (with Id "289") has been added to the diving log ("DivesAdded" list), while the second one has been skipped (duplicate of already existing dive) - ("DivesSkipped" list):

<?xml version="1.0" encoding="UTF-8"?>
<DiveIo>
  <DivesAdded>
    <Dive>
      <Id>289</Id>
      <DiveDate>2010-08-10</DiveDate>
      <InTime>11:14:00</InTime>
      <Duration>00:28:10</Duration>
      <MaxDepth>14.4</MaxDepth>
      <DiverId>4</DiverId>
      <DiveNumber>17</DiveNumber>
    </Dive>
  </DivesAdded>
  <DivesSkipped>
    <Dive>
      <DiveDate>2010-09-18</DiveDate>
      <InTime>14:33:00</InTime>
      <Duration>00:40:30</Duration>
      <MaxDepth>33</MaxDepth>
      <DiverId>4</DiverId>
    </Dive>
  </DivesSkipped>
  <Status>200 OK</Status>
</DiveIo>

POST /self/dives (alternative create method)

For clients that (still) do not support the PUT HTTP method, the server also supports creating new dive log entries via the POST method as "multipart/form-data" ("File upload" POST method).

Description

Same as PUT - creates new dive log entries

Authentication

Required

Request structure

Same file format as for PUT, but this time given as "multipart/form-data" ("File upload"). Content must be given in the POST parameter "xml" for XML files, or "json" for JSON data. Again, files may be gzipped for efficiency.

Response structure

same as "PUT"