[BACK-3011] Document the device_logs metadata and content endpoints.

.gitignore

@@ -7,3 +7,5 @@ build
 .env
 .envrc
 .nvmrc
+.DS_Store
+Session.vim

reference/blob.v1.yaml

@@ -55,7 +55,7 @@ paths:
     post:
       operationId: UploadDeviceLogs
       summary: Upload new device logs as json
-      description: Uploads a new device logs json to the user's account. The `Digest` header must represent the MD5 hash of the json data content.
+      description: Uploads new device logs to the user's account. The `Digest` header must represent the MD5 hash of the data.
       parameters:
         - $ref: ./common/parameters/digestmd5.v1.yaml
         - $ref: ./blob/parameters/logs-start-at.v1.yaml
@@ -66,9 +66,10 @@ paths:
         content:
           application/json:
             schema:
-              type: array
-              items:
-                $ref: ./blob/models/device-log-content.v1.yaml
+              $ref: ./blob/models/device-log-content-list.v1.yaml
+          text/plain:
+            schema:
+              type: string
       responses:
         '201':
           $ref: '#/components/responses/DeviceLogsMetadata'
@@ -89,6 +90,8 @@ paths:
       parameters:
         - $ref: ./blob/parameters/start-at.v1.yaml
         - $ref: ./blob/parameters/end-at.v1.yaml
+        - $ref: ./common/parameters/paginationpage.v1.yaml
+        - $ref: ./common/parameters/paginationsize.v1.yaml
       responses:
         '200':
           $ref: '#/components/responses/DeviceLogsMetadataList'
@@ -103,6 +106,28 @@ paths:
       tags:
         - Device Logs
 
+  '/v1/device_logs/{deviceLogId}/content':
+    parameters:
+      - $ref: './blob/parameters/device-log-id.v1.yaml'
+    get:
+      operationId: GetDeviceLogContent
+      summary: Get the content of a device log.
+      description: >-
+        Retrieves the content, the actual data, of a device log.
+      responses:
+        '200':
+          $ref: '#/components/responses/DeviceLogContent'
+        '400':
+          $ref: './common/responses/badrequest.v1.yaml'
+        '401':
+          $ref: './common/responses/unauthorized.v1.yaml'
+        '403':
+          $ref: './common/responses/forbidden.v1.yaml'
+        '404':
+          $ref: './common/responses/notfound.v1.yaml'
+      tags:
+        - Device Logs
+
   '/v1/users/{userId}/blobs':
     parameters:
       - $ref: ./common/parameters/tidepooluserid.yaml
@@ -280,8 +305,20 @@ components:
         '*/*':
           schema:
             $ref: './blob/models/content.v1.yaml'
+    DeviceLogContent:
+      description: Device log content.
+      content:
+        application/json:
+          schema:
+            $ref: ./blob/models/device-log-content-list.v1.yaml
+        text/plain:
+          schema:
+            type: string
+            example: >-
+              Any kind of arbritrary log data sent by a device. Establishing
+              connection... Connection established. Sending logs...
     DeviceLogsMetadata:
-      description: Device logs metadata
+      description: Device logs metadata. This is information about the log data, but is not the actual log data.
       content:
         application/json:
           schema:

reference/blob/models/device-log-content-list.v1.yaml

@@ -0,0 +1,16 @@
+title: Contents of a device log.
+type: array
+minItems: 0
+items:
+  $ref:  './device-log-content.v1.yaml'
+example:
+  - type: send
+    managerIdentifier: 'Devicey McDeviceface'
+    deviceIdentifier: 'MMT-1711:12345678'
+    timestamp: '2017-02-06T02:37:46Z'
+    message: 'sent something ...'
+  - type: connection
+    managerIdentifier: 'Devicey McDeviceface'
+    deviceIdentifier: 'MMT-1711:12345678'
+    timestamp: '2017-02-06T02:36:50Z'
+    message: 'establishing connection ...'

reference/blob/parameters/device-log-id.v1.yaml

@@ -0,0 +1,7 @@
+description: >-
+  DeviceLog ID
+name: deviceLogId
+in: path
+required: true
+schema:
+  $ref: '../models/id.v1.yaml'

reference/blob/parameters/end-at.v1.yaml

@@ -2,6 +2,6 @@ description: >-
   End At Datetime
 name: endAtTime
 in: query
-required: true
+required: false
 schema:
   $ref: '../../common/models/datetime.v1.yaml'

reference/blob/parameters/start-at.v1.yaml

@@ -2,6 +2,6 @@ description: >-
   Start At Datetime
 name: startAtTime
 in: query
-required: true
+required: false
 schema:
   $ref: '../../common/models/datetime.v1.yaml'