From 9c21ac586488e069761bf233b0d67f294644ba8b Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:26:05 +0300 Subject: [PATCH 01/17] Basic description. --- docs/developers/api-design.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/developers/api-design.md diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md new file mode 100644 index 0000000000..8e051d91b6 --- /dev/null +++ b/docs/developers/api-design.md @@ -0,0 +1 @@ +This document contains the design overview for the Apinf Administrative API. From fb218781e96af8d9a9cfb7fc7c3bd02ebba6ee3b Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:29:15 +0300 Subject: [PATCH 02/17] Versioning. Related #159. --- docs/developers/api-design.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 8e051d91b6..64b0cdbdac 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -1 +1,9 @@ +# Apinf API Design This document contains the design overview for the Apinf Administrative 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/.../ +``` From 090b94ed1b944350042d7d2eb29203a9e423c5f4 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:31:20 +0300 Subject: [PATCH 03/17] URL Route Related #157 --- docs/developers/api-design.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 64b0cdbdac..51453930c9 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -1,6 +1,13 @@ # 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: From 505676d5b54d70010a747cc1062af7a95c82419b Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:31:50 +0300 Subject: [PATCH 04/17] Sub-headings. #157 --- docs/developers/api-design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 51453930c9..3b5261d9b1 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -1,14 +1,14 @@ # Apinf API Design This document contains the design overview for the Apinf Administrative API. -# URL Route +## URL Route The Apinf Administrative API will be designated by the `/api/` URL route: ``` https://apinf.com/api/.../ ``` -# Versioning +## 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: ``` From 09f514cad06f97d4142aca340085c7d08514fe5c Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:34:12 +0300 Subject: [PATCH 05/17] API Documentation #157 --- docs/developers/api-design.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 3b5261d9b1..82b1b965f4 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -14,3 +14,6 @@ The Apinf API will change over time. As such, we will use a numbered versioning ``` 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. From ce875c7d225a763e2d48f6c9fb495d1252f6adde Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:39:22 +0300 Subject: [PATCH 06/17] System Model #159 --- docs/developers/api-design.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 82b1b965f4..7d6297994e 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -17,3 +17,6 @@ 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. From 1878b1949f1b32037ef1024da0460d2978e31ce1 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:41:37 +0300 Subject: [PATCH 07/17] Users #159 --- docs/developers/api-design.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 7d6297994e..44036f9e0d 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -20,3 +20,6 @@ Initially, the Apinf Administrative API will be documented in [Swagger format](h ## 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. From 14416e4b8b414612f74455c6f1acd1faec26734e Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:41:54 +0300 Subject: [PATCH 08/17] Individual Users #159 --- docs/developers/api-design.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 44036f9e0d..a68d7bf648 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -23,3 +23,6 @@ The Apinf system model contains several related data collections. Each collectio ### Users Apinf users will be available via the `/users/` endpoint. + +#### Individual Users +Individual users will be available via `/users/` From 9b6292f9c1f40a5ede60c60ddd277089d20b65f6 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 20 Jul 2015 15:43:49 +0300 Subject: [PATCH 09/17] API Backends #159 --- docs/developers/api-design.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index a68d7bf648..06020eb122 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -26,3 +26,8 @@ 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. + + From bd952fa632b1d5a4400ed13d4bbe3166c14d217c Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:42:58 +0300 Subject: [PATCH 10/17] Basic API description --- docs/developers/api-docs.swagger | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/developers/api-docs.swagger diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger new file mode 100644 index 0000000000..786dd6a9f5 --- /dev/null +++ b/docs/developers/api-docs.swagger @@ -0,0 +1,15 @@ +# 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 From aaa1697af45e130e55a5f321b255c7d404af4485 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:43:26 +0300 Subject: [PATCH 11/17] Users endpoint and User definition --- docs/developers/api-docs.swagger | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger index 786dd6a9f5..8fe21b937d 100644 --- a/docs/developers/api-docs.swagger +++ b/docs/developers/api-docs.swagger @@ -13,3 +13,35 @@ schemes: 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/User' + default: + description: Unexpected error + schema: + $ref: '#/definitions/Error' + definitions: + User: + properties: + user_id: + type: string + description: Unique identifier representing a specific user. From 2ddf0bdeb22e7e479df0c9314b4f04959adb395d Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:45:19 +0300 Subject: [PATCH 12/17] Changed to user_id --- docs/developers/api-docs.swagger | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger index 8fe21b937d..4c6b5a119c 100644 --- a/docs/developers/api-docs.swagger +++ b/docs/developers/api-docs.swagger @@ -20,7 +20,7 @@ paths: description: | The Users endpoint returns information about Apinf users parameters: - - name: id + - name: user_id in: query description: ID of a given user. required: false From 32694b43a39ad0e9dd63b85503079f0546fafe06 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:47:19 +0300 Subject: [PATCH 13/17] Error definition. --- docs/developers/api-docs.swagger | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger index 4c6b5a119c..2a81bbe0e0 100644 --- a/docs/developers/api-docs.swagger +++ b/docs/developers/api-docs.swagger @@ -45,3 +45,12 @@ paths: user_id: type: string description: Unique identifier representing a specific user. + Error: + properties: + code: + type: integer + format: int32 + message: + type: string + fields: + type: string From 4426f9c6e6530ed0165501e67d4ee211ad4864b5 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:53:20 +0300 Subject: [PATCH 14/17] API Bacends endpoint and model --- docs/developers/api-docs.swagger | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger index 2a81bbe0e0..a5fd9331f7 100644 --- a/docs/developers/api-docs.swagger +++ b/docs/developers/api-docs.swagger @@ -39,12 +39,42 @@ paths: 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: User: properties: user_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: From cbd1039a9f7409144e8b2de36e5a852ad529de41 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:57:50 +0300 Subject: [PATCH 15/17] Plural model definition. --- docs/developers/api-docs.swagger | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger index a5fd9331f7..277358dcaf 100644 --- a/docs/developers/api-docs.swagger +++ b/docs/developers/api-docs.swagger @@ -34,7 +34,7 @@ paths: schema: type: array items: - $ref: '#/definitions/User' + $ref: '#/definitions/Users' default: description: Unexpected error schema: @@ -65,7 +65,7 @@ paths: schema: $ref: '#/definitions/Error' definitions: - User: + Users: properties: user_id: type: string From 4d7f777c3af9dcf263711b3be08e7a979ae01bc2 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 22 Jul 2015 10:58:21 +0300 Subject: [PATCH 16/17] Changed user_id to id --- docs/developers/api-docs.swagger | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/api-docs.swagger b/docs/developers/api-docs.swagger index 277358dcaf..9e73881487 100644 --- a/docs/developers/api-docs.swagger +++ b/docs/developers/api-docs.swagger @@ -20,7 +20,7 @@ paths: description: | The Users endpoint returns information about Apinf users parameters: - - name: user_id + - name: id in: query description: ID of a given user. required: false @@ -67,7 +67,7 @@ paths: definitions: Users: properties: - user_id: + id: type: string description: Unique identifier representing a specific user. Backends: From 09b21abeaf7c8914953b807bfada719673a18b03 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 3 Aug 2015 09:59:00 +0300 Subject: [PATCH 17/17] Vendor neutral. --- docs/developers/api-design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/api-design.md b/docs/developers/api-design.md index 06020eb122..f355ef9871 100644 --- a/docs/developers/api-design.md +++ b/docs/developers/api-design.md @@ -5,14 +5,14 @@ This document contains the design overview for the Apinf Administrative API. The Apinf Administrative API will be designated by the `/api/` URL route: ``` -https://apinf.com/api/.../ +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://apinf.com/api/v1/.../ +https://example.com/api/v1/.../ ``` ## API Documentation