Subsurface webservice API

The API can be used to create a user, upload a dive or retrieve the dives of a user.

Register a new login

This happens at the url /api/user/new/email. It needs one argument and will just return a json containing the new identifier.

  • Email address

Example output:

{"user": "EF3LIBCCSQNL5LBZ5LQL8W00YL4254"}

Please note that this identifier will not be activated until the user has confirmed the validity of his email by following the instruction sent by email.

Lost login

This happens at the url /api/user/lost/email It needs one argument and will just return a json containing information on wether the request worked or not (and if so, why not).

  • Email address

Example output:

{"request": "notok", "error": "Email unknown"}
{"request": "ok"}

Delete login

This happens at the url /api/user/delete/ It needs two arguments and will just return a json containing information on wether the request worked or not (and if so, why not).

In fact this method will 'flag' the user as someone who has asked for his account to be removed but the actual removal will only be done once it has been confirmed by email.

  • Email address
  • Diver ID

This method only accepts POST calls.

Example output:

{"request": "notok", "error": "Email unknown"}
$ curl --data "login=EF3LIBCCSQNL5LBZ5LQL8W00YL4254&email=something@example.org" http://...../api/user/delete/ {"request": "ok"}

Upload a new dive

This happens at the url /api/dive/add/ It will require for arguments:

  • 'login': The login identifier
  • 'dive_latitude': The latitude
  • 'dive_longitude': The longitude
  • 'dive_date': Date (format: yyyy-mm-dd)
  • 'dive_time': Time (format: hh:mm(:ss))
  • 'dive_name': The dive name

This method only accepts POST calls.

Example output:

{"upload": "ok"}

curl example:

$ curl --data "login=EF3LIBCCSQNL5LBZ5LQL8W00YL4254&dive_date=2012-10-02&dive_latitude=12&dive_longitude=34.5&dive_time=09:30" http://...../api/dive/add/ {"upload": "ok"}

Delete dives

This happens at the url /api/dive/delete/ It needs three arguments and will just return a json containing information on wether the request worked or not (and if so, why not).

  • Diver ID
  • Dive date
  • Dive time

This method only accepts DELETE calls.

Example output:

{"delete": "notok", "error":"No dive found for the provided information."}
$ curl -X DELETE --data "login=EF3LIBCCSQNL5LBZ5LQL8W00YL4254&dive_date=2013-20-02&dive_time=16:00" http://...../api/dive/delete/ {"request": "ok"}

Retrieve someone's dives

JSON output

This happens at the url /api/dive/get/?login=login. It will require one arguments:

  • 'login': The login identifier

The output format is 'application/json' by default, this can be changed to 'text/xml' via the 'Accept' header.

Example JSON output:

$ curl http://...../api/dive/get/?login=EF3LIBCCSQNL5LBZ5LQL8W00YL4254 { "user": "EF3LIBCCSQNL5LBZ5LQL8W00YL4254", "dives": [ { "name": "dive1", "latitude": "12", "longitude": "23", "date": "2012-10-02", "time": "12:00:00" }, { "name": "dive2", "latitude": "23", "longitude": "34", "date": "2012-10-02", "time": "16:00:00" } ], "download": "ok" }

Example XML output:

$ curl -H 'Accept: text/xml' http://...../api/dive/get/?login=EF3LIBCCSQNL5LBZ5LQL8W00YL4254 <?xml version="1.0" encoding="UTF-8" ?> <output> <user>EF3LIBCCSQNL5LBZ5LQL8W00YL4254</user> <dives> <dive> <name>dive1</name> <latitude>12</latitude> <longitude>23</longitude> <date>2012-10-02</date> <time>12:00:00</time> </dive> <dive> <name>dive2</name> <latitude>23</latitude> <longitude>34</longitude> <date>2012-10-02</date> <time>16:00:00</time> </dive> </dives> <download>ok</download> </output>