Add OpenAPI docs

api/openapi.yaml

@@ -0,0 +1,183 @@
+openapi: 3.0.0
+info:
+  version: 0.1.0
+  title: NanoMDM API
+paths:
+  /v1/pushcert:
+    put:
+      description: Upload APNs certificate and private key.
+      security:
+        - basicAuth: []
+      requestBody:
+        description: The request body includes the APNs certificate and private key in PEM-encoded format concatenated together *without* any wrapping or container formats like JSON. The private key must *not* be encrypted.
+        required: true
+        content:
+          text/plain:
+            schema:
+              type: string
+            example: |-
+              -----BEGIN CERTIFICATE-----
+              MIIFdjCCBF6gAwIBAgIIZ7SjAeWsGIwwDQYJKoZIhvcNAQELBQAwgYwxQDA+BgNV
+              [..snip..]
+              lL5jy74l8Za59w==
+              -----END CERTIFICATE-----
+              -----BEGIN RSA PRIVATE KEY-----
+              MIIEogIBAAKCAQEAyfyVbzvN3t0RZgemV2YNGByPjIC3nAyMeabAg/xh/RlqS1uY
+              [..snip..]
+              ThmdpyJ76efnVCpgta/av0LZ6S9914MJpw2ff6H2Ou3y54Jy/94=
+              -----END RSA PRIVATE KEY-----
+      responses:
+        '200':
+          description: The "topic" (UID attribute) from the uploaded APNs certificate is returned or any errors that occured with the upload and storage.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                  topic:
+                    type: string
+                    description: The "topic" (UID attribute) from the uploaded APNs certificate.
+                    example: 'com.apple.mgmt.External.e3b8ceac-1f18-2c8e-8a63-dd17d99435d9'
+        '401':
+           $ref: '#/components/responses/UnauthorizedError'
+        '500':
+          description: Error reading HTTP body from request
+  /v1/push/{id*}:
+    get:
+      description: Send APNs push notifications to MDM enrollments
+      security:
+        - basicAuth: []
+      responses:
+        '200':
+          description: API response. Can include errors in response object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIResult'
+        '401':
+           $ref: '#/components/responses/UnauthorizedError'
+      parameters:
+        - $ref: '#/components/parameters/idParam'
+  /v1/enqueue/{id*}:
+    put:
+      description: Enqueue MDM commands to MDM enrollments and (optionally) send APNs push notifications
+      security:
+        - basicAuth: []
+      requestBody:
+        description: The request body is an XML-encoded MDM command plist.
+        required: true
+        content:
+          text/plain:
+            # Apple plists can't cleanly be represented in OpenAPI specification so we have to fake the Content-Type as text/plain.
+            schema:
+              type: string
+            example: |-
+              <?xml version="1.0" encoding="UTF-8"?>
+              <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+              <plist version="1.0">
+              <dict>
+                <key>Command</key>
+                <dict>
+                  <key>RequestType</key>
+                  <string>ProfileList</string>
+                </dict>
+                <key>CommandUUID</key>
+                <string>fedd659e-fc3c-4e35-8bb1-c8f51ae542a5</string>
+              </dict>
+              </plist>
+      responses:
+        '200':
+          description: API response. Can include errors in response object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIResult'
+        '400':
+          description: Error decoding MDM command plist.
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '500':
+          description: Error reading HTTP body from request
+      parameters:
+        - $ref: '#/components/parameters/idParam'
+        - in: query
+          name: nopush
+          schema:
+            type: string
+            example: '1'
+  /version:
+    get:
+      description: Returns the running NanoMDM version
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema: 
+                type: object
+                properties: 
+                  version:
+                    type: string
+                example:
+                  version: "v0.1.0"
+components:
+  parameters:
+    idParam:
+      name: id*
+      in: path
+      description: Enrollment ID(s) of device- or user-channel enrollments. Typically a UUID-looking identifier.
+      required: true
+      explode: true
+      style: simple
+      schema:
+        type: array
+        items:
+          type: string
+        minItems: 1
+        example: ['299BD49-1A0C-422C-B285-2E4FF087C673', 'E2E4A8EB-45EE-488D-B9D7-4CC3B1C40699']
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+  responses:
+    UnauthorizedError:
+      description: API key is missing or invalid.
+      headers:
+        WWW-Authenticate:
+          schema:
+            type: string
+  schemas:
+    APIResult:
+      type: object
+      description: foo
+      properties:
+        no_push:
+          type: boolean
+          default: false
+        push_error:
+          type: string
+        command_error:
+          type: string
+        command_uuid:
+          type: string
+          example: 'c7fc0872-f22f-4823-8ae0-f3d0174fb48a'
+          format: uuid
+        request_type:
+          type: string
+        status:
+          type: object
+          properties:
+            $id:
+              type: object
+              properties:
+                push_error:
+                  type: string
+                push_result:
+                  type: string
+                  format: uuid
+                  example: '6E14E52F-7F07-42C7-8367-4D81441DC85F'
+                  description: Push UUID from Apple Push Notification service servers.
+                command_error:
+                  type: string