Skip to content

logs.md

Latest commit

 

History

History
308 lines (272 loc) · 13.4 KB

logs.md

File metadata and controls

308 lines (272 loc) · 13.4 KB

Dive Log Entries

Back to API documentation

Dive Log Entry Objects

Many of the log entry APIs accept or return a Dive Log Entry Object. Here is the specification:

{
	logId: [uuid],
	ownerId: [userId],
	entryTime: [dateAndTime],
	diveNumber: [integer]
	diveTime: {
		exitTime: [dateAndTime],
		surfaceInterval: [integer],
		bottomTime: [dateAndTime],
		decoStops: [
			{
				depth: [number],
				duration: [integer]
			}
		]
	},
	location: [string],
	site: [string],
	gps: {
		latitude: [string],
		longitude: [string]
	},
	cnsO2Percent: [number],
	cylinders: [
		{
			gas: {
				o2Percent: [number],
				hePercent: [number],
				startPressure: [number],
				endPressure: [number]
			},
			volume: [number],
			type: [string],
			number: [number]
		}
	],
	depth: {
		average: [number],
		max: [number]
	},
	temperature: {
		surface: [number],
		water: [number],
		thermocline1: [number],
		thermocline2: [number]
	},
	exposure: {
		body: [string],
		thickness: [number],
		gloves: [boolean],
		hood: [boolean],
		boots: [boolean]
	},
	equipment: {
		compass: [boolean],
		computer: [boolean],
		knife: [boolean],
		light: [boolean],
		scooter: [boolean],
		slate: [boolean],
		surfaceMarker: [boolean]
	},
	diveType: {
		altitude: [boolean],
		boat: [boolean],
		cave: [boolean],
		deep: [boolean],
		drift: [boolean],
		ice: [boolean],
		night: [boolean],
		reef: [boolean],
		saltWater: [boolean],
		searchAndRecovery: [boolean],
		training: [boolean],
		wreck: [boolean]
	},
	visibility: [string],
	current: [string],
	surfaceConditions: [string],
	weather: [string],
	mood: [string],
	weight: {
		amount: [number],
		correctness: [string],
		trim: [string],
		notes: [string]
	},
	notes: [string]
}
  • logId: A uuid that uniquely identifies the log entry. This is not required when posting, putting, or patching entries - the Log ID will be provided in the route path.
  • ownerId: The ID of the user who owns the log entry. This is not required when posting, putting, or patching entries - the user will be provided in the route path.
  • entryTime: Required. An ISO date/time string (ISO 8601) that indicates when the dive took place (i.e. the start of the descent.)
  • diveNumber: A positive integer indicating the dive number for allowing the user to track how many dives they have under their belt.
  • diveTime:
    • diveLength: Required; a positive integer. The number of minutes the dive lasted for.
    • exitTime: An ISO date/time indicating the dive exit time (i.e. when the diver returned to the surface.)
    • surfaceInterval: A positive integer. Number of minutes of surface interval since the previous dive, if applicable.
    • bottomTime: A positive integer. Number of minutes of bottom time for the dive. (I.e. The number of minutes from the beginning of the initial descent to the beginning of the final ascent.)
    • decoStops: An array of decompression stops made on this dive. May contain up to 10 stops.
      • depth: A positive number at which the depth at which the stop took place.
      • duration: A positive integer indicating the number of minutes that the stop took place for.
  • location: Required. The place or city at which the time took place. Max length is 250 characters.
  • site: Required. The name of the dive site. Max length is 250 characters.
  • gps: The GPS coordinates for the dive site.
    • latitude: A string containing either the decimal or sexagesimal representation of latitude coordinates.
    • longitude: A string containing either the decimal or sexagesimal representation of longitude coordinates.
  • cnsO2Percent: A positive number between 0 and 150 indicating the diver's CNS O2 exposure (percent of maximum) at the end of the dive.
  • cylinders: An array listing the cylinders that the diver had with them on this dive. Up to 10 entries are allowed.
    • gas:
      • o2Percent: A number between 1 and 100 indicating the percentage of the gas blend that was oxygen.
      • hePercent: A number between 0 and 99 indicating the percentage of the gas blend that was helium.
      • startPressure: A positive number indicating the starting pressure of the cylinder(s). Maximum is 5000psi.
      • endPressure: A positive number indicating the pressure of the cylinder(s). Maximum is 5000psi unless startPressure is specified - it must be less than startPressure.
    • volume: A positive number indicating the volume of the cylinder. Maximum 200cf.
    • type: A string. Valid values are aluminum or steel.
    • number: A positive integer indicating the number of tanks in the configuration. (E.g. 2 for doubles.)
  • depth:
    • average: A positive number indicating the average depth of the dive. Maximum 1000ft unless max is specified - it must be less than max.
    • max: Required. A positive number indicating the maximum depth of the dive. Maximum 1000ft.
  • temperature:
    • surface: A number indicating the surface temperature. Must be between -76F and 150F.
    • water: A number indicating the water temperature at the surface. Must be between 30F and 150F.
    • thermocline1: A number indicating the water temperature below the first thermocline. Must be between 30F and 150F.
    • thermocline2: A number indicating the water temperature below the second thermocline. Must be between 30F and 150F.
  • exposure:
    • body: String. Valid values are none, shorty, full, and dry.
    • thickness: Integer indicating the thickness of the wetsuit, if applicable, (usually 3, 5, or 7mm.) Maximum is 10mm.
    • gloves: Boolean. True if gloves were worn on the dive.
    • hood: Boolean. True if a hood was worn on the dive.
    • boots: Boolean. True if boots were worn on the dive.
  • equipment:
    • compass: Boolean. True if a compass was worn on the dive.
    • computer: Boolean. True if a computer was worn on the dive.
    • knife: Boolean. True if a knife was carried on the dive.
    • light: Boolean. True if a light was carried on the dive.
    • scooter: Boolean. True if a scooter was brought along on the dive.
    • slate: Boolean. True if a slate was carried on the dive.
    • surfaceMarker: True if a surface marker was carried on the dive.
  • diveType:
    • altitude: Boolean. True for altitude dives.
    • boat: Boolean. True for boat dives (as opposed to shore dives.)
    • cave: Boolean. True for cave dives.
    • deep: Boolean. True for deep dives.
    • drift: Boolean. True for drift dives.
    • ice: Boolean. True for ice dives.
    • night: Boolean. True for night dives.
    • reef: Boolean. True for reef dives.
    • saltWater: Boolean. True for salt water dives (as opposed to fresh.)
    • searchAndRecovery: Boolean. True for search and recovery dives.
    • training: Boolean. True for training dives.
    • wreck: Boolean. True for wreck dives.
  • visibility: A string indicating visibility on the dive. Valid values are none, poor, moderate, good, excellent, and ultra.
  • current: A string indicating the strength of the current on the dive. Valid values are none, mild, moderate, fast, and extreme.
  • surfaceConditions: A string indicating the surface conditions. Valid values are calm, moderate, rough, and insane.
  • weather: A string indicating the weather during the dive. Valid values are sunny, mainlySunny, overcast, rainy, and stormy.
  • mood: A string indicating how the diver felt about the dive. Valid values terrible, bad, ok, good, and excellent.
  • weight: {
    • amount: A positive number indicating how much ballast weight the diver was wearing. Maximum 100lbs.
    • correctness: A string indicating how well the diver was weighted. Valid values are good, too much, or too little.
    • trim: A string indicating how the diver's trim was. Valid values are good, head up, or head down.
    • notes: A free-form string for making notes on weight configuration. Maximum length is 500 characters.
  • notes: A free-form string for making notes on the dive in general. Maximum length is 1500 characters.

List Log Entries

Gets an ordered list of dive log entries for a user.

Route

GET /api/logs/:userName/
  • :userName The user name that identifies the user for which log entries should be returned.

Query Params

?before=2017-04-21T09:18:00.000Z&after=2017-01-01T00:00:00.000Z&order=desc&limit=50

All of the query parameters are optional.

  • order: Valid values are asc or desc. Results are ordered by the dive entry times. The default is descending order (reverse-chronological order.) For chronological order set order to asc.
  • before: An ISO 8601 date and time string. When specified, only log entries with dive entry times that occurred before this time will be returned.
  • after: An ISO 8601 date and time string. When specified, only log entries with dive entry times that occurred after this time will be returned.
  • limit: The maximum number of records to return in the result set. Must be a positive integer between 1 and 1000.

Success Response

  • Status Code: 200

Returns an array of dive log entries matching the supplied query parameters. The entries will contain a subset of the fields for a full dive log entry:

[
	{
		logId: [uuid],
		ownerId: [userId],
		entryTime: [isoDate],
		location: [string],
		site: [string],
		depth: {
			average: [number],
			max: [number]
		}
	},
	...
]

Error Response

  • Status Code 400: Bad request. One or more of the query string parameters is invalid.
  • Status Code 401: Not authorized. The current user is not authorized to view the log book for the requested :userName or the current user is unauthenticated.
  • Status Code 500: Internal server error.

Create New Dive Log Entry

Creates a new dive log entry in the specified user's log book.

Route

POST /api/logs/:userName/
  • :userName The user name that identifies the user for which log entries should be returned.

Data Params

The method accepts a Dive Log Entry Object.

Success Response

  • Status Code: 200

The newly-created Dive Log Entry Object is returned with logId and createdAt fields populated.

Error Response

  • Status Code 400: Bad request. One or more of the fields of the new log entry was invalid. See Dive Log Entry Object for the proper specification.
  • Status Code 401: Not authorized. The current user is not permitted to add logs to the log book for the requested :userName or the current user is unauthenticated.
  • Status Code 403: Forbidden. The ownerId field was set to a value that did not match the user Id of the user indicated in the :userName route parameter.
  • Status Code 500: Internal server error.

Retrieve a Dive Log Entry

Retrieves a log entry from the specified user's log book.

Route

GET /api/logs/:userName/:logId/
  • :userName The user name that identifies the user for which log entries should be returned.
  • :logId The ID of the log entry to be retrieved.

Success Response

  • Status Code: 200

The Dive Log Entry Object is returned in the response body.

Error Response

  • Status Code 401: Not authorized. The current user is not permitted to view the entries in the log book for the requested :userName or the current user is unauthenticated.
  • Status Code 500: Internal server error.

Delete a Dive Log Entry

Deletes a log entry from the specified user's log book.

Route

DELETE /api/logs/:userName/:logId/
  • :userName The user name that identifies the user for which log entry should be deleted.
  • :logId The ID of the log entry to be deleted.

Success Response

  • Status Code: 200

Error Response

  • Status Code 401: Not authorized. The current user is not permitted to delete the entries in the log book for the requested :userName or the current user is unauthenticated.
  • Status Code 500: Internal server error.

Update An Existing Dive Log Entry

Creates a new dive log entry in the specified user's log book.

Route

PUT|PATCH /api/logs/:userName/:logId/
  • :userName The user name that identifies the user for which the log entry should be updated.
  • :logId The ID of the log entry to be updated.

This route will respond on both PUT and PATCH HTTP verbs. (Technically, the operation is more of a PATCH but PUT is aliased nonetheless.)

Data Params

The method accepts a Dive Log Entry Object with updated field values. Fields that are not being updated can be omitted - they will retain their values. Non-required fields can be deleted by setting their values to null.

Success Response

  • Status Code: 200

The newly-created Dive Log Entry Object is returned with logId and createdAt fields populated.

Error Response

  • Status Code 400: Bad request. One or more of the fields of the new log entry was invalid. See Dive Log Entry Object for the proper specification.
  • Status Code 401: Not authorized. The current user is not permitted to add logs to the log book for the requested :userName or the current user is unauthenticated.
  • Status Code 403: Forbidden. A forbidden action was taken. One of:
    • The ownerId field was set to a value that did not match the user Id of the user indicated in the :userName route parameter.
    • A required field was requested to be removed (by setting it's value to null in the request body.)
  • Status Code 500: Internal server error.