Updated docs

linlin2018 · Jun 1, 2019 · 278acf6 · 278acf6
1 parent 88d1882
commit 278acf6
Show file tree

Hide file tree

Showing 7 changed files with 523 additions and 44 deletions.
diff --git a/docs/api/agents.md b/docs/api/agents.md
@@ -0,0 +1,199 @@
+## create
+
+Creates a new Agent resource. The Domain must exist before creating the Agent. Otherwise, this method responds with a `UNFULFILLED_DEPENDENCY_RESPONSE`.
+
+**URL**
+
+`/agents`
+
+**Method**
+
+`POST`
+
+**Parameters**
+
+This method does not receive any parameters.
+
+**Request body**
+
+A file containing an [Agent](/configuration/agents) resource in `json` or `yaml` format.
+
+**Response**
+
+If successful this method creates an Agent resource.
+
+**Sample Call**
+
+```json
+POST /api/{apiversion}/agents
+- apiVersion: v1beta1
+  kind: Agent
+  metadata:
+    name: John Doe
+  spec:
+    credentials:
+      username: '1001'
+      secret: '1234'
+    domains: [sip.local]
+
+HTTP/1.1 201 Created
+{"status": "201", "Successful request"}
+```
+
+## delete
+
+Removes an Agent resource from a persistent database.
+
+**URL**
+
+`/agents`
+
+**Method**
+
+`DELETE`
+
+**Parameters**
+
+| Parameter Name | Type   | Value | Description
+| ---  | :--------- |  :--------- |  :--------- |
+| id |  path | string | Resource identifier|
+
+**Request body**
+
+Do not supply a request body with this method.
+
+**Response**
+
+If successful this method removes an Agent resource.
+
+**Sample Call**
+
+```json
+DELETE /api/{apiversion}/agents/{id}
+{
+
+}
+
+HTTP/1.1 200 OK
+{"status": "200", "Successful request"}
+```
+
+## get
+
+This method returns an Agent resource.
+
+**URL**
+
+`/agents`
+
+**Method**
+
+`GET`
+
+**Parameters**
+
+| Parameter Name | Type   | Value | Description
+| ---  | :--------- |  :--------- |  :--------- |
+| id |  path | string | Resource identifier|
+
+
+**Request body**
+
+Do not supply a request body with this method.
+
+**Response**
+
+If successful this method returns an Agent resource.
+
+**Sample Call**
+
+```json
+GET /api/{apiversion}/agents/{id}
+{
+
+}
+
+HTTP/1.1 200 OK
+{"status": "200", "Successful request"}
+```
+
+## list
+
+This method returns a list of Agent resources.
+
+**URL**
+
+`/agents`
+
+**Method**
+
+`GET`
+
+**Parameters**
+
+| Parameter Name | Type   | Value | Description
+| ---  | :--------- |  :--------- |  :--------- |
+| filter |  query | string | Use filter to narrow the elements shown. |
+
+**Request body**
+
+Do not supply a request body with this method.
+
+**Response**
+
+If successful this method returns a list of Agent resources.
+
+**Sample Call**
+
+```json
+GET /api/{apiversion}/agents
+{
+
+}
+
+HTTP/1.1 200 OK
+{"status": "200", "Successful request"}
+```
+
+## update
+
+Updates am existing Agent resource.
+
+**URL**
+
+`/agents`
+
+**Method**
+
+`PUT`
+
+**Parameters**
+
+This method does not receive any parameters.
+
+**Request body**
+
+A file containing an [Agent](/configuration/agents) resource in `json` or `yaml` format.
+
+**Response**
+
+If successful this method updates an Agent resource.
+
+**Sample Call**
+
+```json
+PUT /api/{apiversion}/agents/{id}
+- apiVersion: v1beta1
+  kind: Agent
+  metadata:
+    name: John Doe
+    ref: {id}
+  spec:
+    credentials:
+      username: '1001'
+      secret: '1234'
+    domains: [sip.local]
+
+HTTP/1.1 200 OK
+{"status": "200", "Successful request"}
+```
diff --git a/docs/api/credentials.md b/docs/api/credentials.md
@@ -1,6 +1,4 @@
-# Credentials
-
-Gets a token for subsequent API calls
+Gets a token for subsequent API calls.
 
 **URL**
 
@@ -10,25 +8,17 @@ Gets a token for subsequent API calls
 
   `GET`
 
-**URL Params**
-
-  None
-
-**Data Params**
+**Parameters**
 
-  None
+  This method does not receive any parameters.
 
-**Success Response**
+**Request body**
 
-| Code | Content|
-| ---  |:------ |
-| 200 OK  | JWT Token |
+  Do not supply a request body with this method.
 
-**Error Response**
+**Response**
 
-| Code | Content   |
-| ---  | :--------- |
-| 401 UNAUTHORIZED | `{ status: "401", message : "You are unauthorized to make this request." }`|
+  If successful this method returns a string with a token.
 
 **Sample Call**
 

diff --git a/docs/api/location.md b/docs/api/location.md
@@ -1,28 +1,25 @@
-# Location
-
-Gets a list of registered devices
+Gets a list of registered devices.
 
 **URL**
 
-  `/location`
+`/location`
 
 **Method**
 
-  `GET`
+`GET`
 
-**URL Params**
+**Parameters**
 
-  None
+This method does not receive any parameters.
 
-**Data Params**
+**Request body**
 
-  None
+Do not supply a request body with this method.
 
-**Success Response**
+**Response**
 
-| Code | Content   |
-| ---  |:------    |
-| 200  |  |
+This method returns a list with registered devices in
+the response body.
 
 **Sample Call**
 
@@ -33,5 +30,14 @@ GET /api/{apiversion}/location
 }
 
 HTTP/1.1 200 OK
-"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiJ9.O7hC-ta225epRQlJZO44WC-l2cWohKnJ8lkmlOQpw8Z_xYiwJ6-qDUhHeJEZH9DmwIwz_jD77sj1kQUkXHsbOg"
+{  
+   "status":200,
+   "message":"Successful request",
+   "result":[  
+      {  
+         "addressOfRecord":"sip:[email protected]",
+         "contactInfo":"sip:[email protected]:59985;transport=tcp;nat=false;expires=600"
+      }
+   ]
+}
 ```
diff --git a/docs/api/overview.md b/docs/api/overview.md
@@ -1,3 +1,53 @@
-Routr API version is currently `v1beta1`. We continue to improve the API, resource definition, and other artifacts until we reach a final version. We can then establish an update policy to ensure backward compatibility. Until then keep an eye on this document. The endpoint for the API is as follows:
+Routr API version is currently `v1beta1`. We continue to improve the API, resource definition, and other artifacts until we reach a final version. We can then establish an update policy to ensure backward compatibility. Until then keep an eye on this document.
+
+The endpoint for the API is:
 
 `/api/{apiversion}`
+
+## Authentication
+
+Routr's API is authenticated with a JWT token. To obtain the token use the
+`/api/{apiversion}/credentials` endpoint with basic authentication present
+in the [User](/configuration/user) resource. You must them append the `token`
+as a query parameter.
+
+**Sample call**
+
+To obtain the token
+
+```bash
+curl -k -u "admin:changeit" https://localhost:4567/api/v1beta1/credentials
+
+# Resulted in
+eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiJ9.O7hC-ta225epRQlJZO44WC-l2cWohKnJ8lkmlOQpw8Z_xYiwJ6-qDUhHeJEZH9DmwIwz_jD77sj1kQUkXHsbOg
+```
+
+To use the token
+
+```bash
+curl -k -u "admin:changeit" https://localhost:4567/api/v1beta1/location?token=eyJhbGciOiJIUzUxMiJ9.e...
+
+# Resulted in
+{  
+   "status":200,
+   "message":"Successful request",
+   "result":[  
+      {  
+         "addressOfRecord":"sip:[email protected]",
+         "contactInfo":"sip:[email protected]:61147;transport=tcp;nat=false;expires=600"
+      }
+   ]
+}
+```
+
+## Error Responses
+
+The following are general errors we might have to account for:
+
+| Code | Content   |
+| ---  | :--------- |
+| 400 BAD_REQUEST | `{ status: "400", message : "Bad Request" }`|
+| 401 UNAUTHORIZED | `{ status: "401", message : "You are unauthorized to make this request." }`|
+| 405 NOT_SUPPORTED | `{ status: "405", message : "Operation not supported by data source provider" }`|
+| 409 CONFLICT | `{ status: "409", message : "An attempt was made to create an object that already exists" }`|
+| 4091 UNFULFILLED_DEPENDENCY_RESPONSE | `{ status: "4091", message : "Found one or more unfulfilled dependencies" }`|