Refactor API for cleaner RESTful idioms and support pagination and batching

api/openapi.yaml

@@ -34,12 +34,13 @@ paths:
         '400':
           $ref: '#/components/responses/ErrorResponse'
 
-  /list_locations:
+  /locations:
     get:
+      description: Lists all the visible locations to the caller.
       parameters:
         - name: asn
           in: query
-          description: List avaible locations for peering with the given ASN
+          description: List available locations for peering with the given ASN
           required: true
           schema:
             type: integer
@@ -50,22 +51,36 @@ paths:
           required: false
           schema:
             $ref: '#/components/schemas/LocationType'
+        - name: max_results
+          in: query
+          description: Hint to paginate the request with the maximum number of results the caller is able to process.
+          required: false
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+            maximum: 100
+        - name: next_token
+          in: query
+          description: Indication of the offset to retrieve the next page on a previously initiated paginated request.
+          required: true
+          schema:
+            type: string
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Location'
-
+                $ref: '#/components/responses/ListLocationsResponse'
         '400':
           $ref: '#/components/responses/ErrorResponse'
+        '403':
+          $ref: '#/components/responses/ErrorResponse'
 
-  /add_sessions:
+  /sessions:
     post:
-      description: Request peering
+      description: Requests a new set of sessions to be created.
       requestBody:
         description: Request to create peering sessions
         content:
@@ -79,18 +94,20 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SessionArray'
+                $ref: '#/components/responses/CreateSessionsResponse'
         '300':
           description: Request modified or partially accepted
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SessionArray'
+                $ref: '#/components/responses/CreateSessionsResponse'
         '400':
           $ref: '#/components/responses/ErrorResponse'
+        '403':
+          $ref: '#/components/responses/ErrorResponse'
 
-  /get_status:
     get:
+      description: Lists a set of sessions visible to the caller. Each session in the set contains a summary of its current status.
       parameters:
         - name: asn
           in: query
@@ -104,15 +121,32 @@ paths:
           required: false
           schema:
             type: string
+        - name: max_results
+          in: query
+          description: Hint to paginate the request with the maximum number of results the caller is able to process.
+          required: false
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+            maximum: 100
+        - name: next_token
+          in: query
+          description: Indication of the offset to retrieve the next page on a previously initiated paginated request.
+          required: true
+          schema:
+            type: string
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SessionArray'
+                $ref: '#/components/responses/ListSessionsResponse'
         '400':
           $ref: '#/components/responses/ErrorResponse'
+        '403':
+          $ref: '#/components/responses/ErrorResponse'
 
 components:
   schemas:
@@ -138,6 +172,43 @@ components:
         Add choices
       type: string
 
+    LocationArray:
+      title: Locations
+      description: Array of peering locations
+      type: array
+      items:
+        $ref: '#/components/schemas/Location'
+
+    SessionRequestArray:
+      title: BGP Sessions requested
+      description: Array of BGP Sessions requested
+      type: array
+      items:
+        $ref: '#/components/schemas/SessionRequestItem'
+
+    SessionRequestItem:
+      title: BGP Session Request
+      description: BGP Session Request
+      type: object
+      properties:
+        local_asn:
+          type: integer
+        local_ip:
+          type: string
+        peer_asn:
+          type: integer
+        peer_ip:
+          type: string
+        peer_type:
+          type: string
+        md5: # TODO or auth: md5: $key?
+          type: string
+        location:
+          $ref: '#/components/schemas/Location'
+        item_id:
+          type: string
+          description: unique identifier of the session in an aggregate
+
     SessionArray:
       title: BGP Sessions
       description: Array of BGP Sessions
@@ -166,11 +237,14 @@ components:
           $ref: '#/components/schemas/Location'
         status:
           $ref: '#/components/schemas/SessionStatus'
-        uuid:
+        session_id:
           type: string
           description: |-
             unique identifier (also serves as request id)
             Could separate into local_ and peer_?
+        item_id:
+          type: string
+          description: unique identifier of the session in an aggregate
     Error:
       title: Error
       type: object
@@ -206,7 +280,46 @@ components:
         - name
         - errors
 
+  requests:
+    CreateSessionsRequest:
+      title: CreateSessionsRequest
+      description: Response to a request to create sessions
+      type: object
+      properties:
+        sessions:
+          $ref: '#/components/schemas/SessionRequestArray'
+
   responses:
+    ListLocationsResponse:
+      title: ListLocationsResponse
+      description: Response to a list for locations
+      type: object
+      properties:
+        next_token:
+          type: string
+        locations:
+          $ref: '#/components/schemas/LocationArray'
+
+    CreateSessionsResponse:
+      title: CreateSessionsResponse
+      description: Response to a request to create sessions
+      type: object
+      properties:
+        sessions:
+          $ref: '#/components/schemas/SessionArray'
+        errors:
+          $ref: '#/components/schemas/Error'
+
+    ListSessionsResponse:
+      title: ListSessionsResponse
+      description: Response to a list for sessions
+      type: object
+      properties:
+        next_token:
+          type: string
+        sessions:
+          $ref: '#/components/schemas/SessionArray'
+
     ErrorResponse:
       description: API Error response
       content: