diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md new file mode 100644 index 0000000000..f355ef9871 --- /dev/null +++ b/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://example.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://example.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/` + +### API Backends +API Backends will be available via the `/backends/` endpoint. + + diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger new file mode 100644 index 0000000000..9e73881487 --- /dev/null +++ b/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