Feature/apinf api design

docs/developers/api-design.md

@@ -0,0 +1,33 @@
+# Apinf API Design
+This document contains the design overview for the Apinf Administrative API.
+
+## URL Route
+The Apinf Administrative API will be designated by the `/api/` URL route:
+
+```
+https://apinf.com/api/.../
+```
+
+## Versioning
+The Apinf API will change over time. As such, we will use a numbered versioning scheme. Versions will be indicated by integers, starting with **1**. Version numbers will be located in the project URL, such as:
+
+```
+https://apinf.com/api/v1/.../
+```
+
+## API Documentation
+Initially, the Apinf Administrative API will be documented in [Swagger format](http://swagger.io). Swagger is chosen as it is open-source, vender-neutral, and supported by the Apinf platform itself.
+
+## System Model
+The Apinf system model contains several related data collections. Each collection will be represented by an unique endpoint, with the ability to perform traversals to related data sets.
+
+### Users
+Apinf users will be available via the `/users/` endpoint.
+
+#### Individual Users
+Individual users will be available via `/users/<userId>`
+
+### API Backends
+API Backends will be available via the `/backends/` endpoint.
+
+

docs/developers/api-docs.swagger

@@ -0,0 +1,86 @@
+# This document describes the Apinf Administrative API
+swagger: '2.0'
+info:
+  title: Apinf API
+  description: Manage the Apinf platform via an Administrative API
+  version: "0.1.0"
+# the domain of the service
+host: apinf.com
+# array of all schemes that your API supports
+schemes:
+  - https
+# will be prefixed to all paths
+basePath: /api/v1
+produces:
+  - application/json
+paths:
+  /users:
+    get:
+      summary: Apinf Users
+      description: |
+        The Users endpoint returns information about Apinf users
+      parameters:
+        - name: id
+          in: query
+          description: ID of a given user.
+          required: false
+          type: string
+          format: uuid
+      tags:
+        - Users
+      responses:
+        200:
+          description: An array of users
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Users'
+        default:
+          description: Unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+  /backends:
+    get:
+      summary: API Backends
+      description: |
+        API Backends returns an array of configured API Endpoints with their associated backend.
+      parameters:
+        - name: id
+          in: query
+          description: ID of a given API Backend.
+          required: false
+          type: string
+          format: uuid
+      tags:
+        - Backends
+      responses:
+        200:
+          description: An array of API backends
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Backends'
+        default:
+          description: Unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+  definitions:
+  Users:
+    properties:
+      id:
+        type: string
+        description: Unique identifier representing a specific user.
+  Backends:
+    properties:
+      id:
+        type: string
+        description: Unique identifier representing a specific API Backend
+  Error:
+    properties:
+      code:
+        type: integer
+        format: int32
+      message:
+        type: string
+      fields:
+        type: string