From 278acf62d02604b2fe03db50b11c2fc02e18a602 Mon Sep 17 00:00:00 2001 From: Fonoster Team Date: Sat, 1 Jun 2019 16:35:46 -0400 Subject: [PATCH] Updated docs --- docs/api/agents.md | 199 ++++++++++++++++++++++++++++++++++++++++ docs/api/credentials.md | 24 ++--- docs/api/location.md | 34 ++++--- docs/api/overview.md | 52 ++++++++++- docs/api/peers.md | 198 +++++++++++++++++++++++++++++++++++++++ docs/api/registry.md | 37 ++++++++ mkdocs.yml | 23 +++-- 7 files changed, 523 insertions(+), 44 deletions(-) create mode 100644 docs/api/agents.md create mode 100644 docs/api/peers.md create mode 100644 docs/api/registry.md diff --git a/docs/api/agents.md b/docs/api/agents.md new file mode 100644 index 000000000..b92a7800a --- /dev/null +++ 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 index 37fb223bc..392338b1b 100644 --- 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 index e9954225e..c646d3a1b 100644 --- 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:1001@sip.local", + "contactInfo":"sip:45962087@192.168.1.127:59985;transport=tcp;nat=false;expires=600" + } + ] +} ``` diff --git a/docs/api/overview.md b/docs/api/overview.md index d64173c6c..813515e4e 100644 --- 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:1001@sip.local", + "contactInfo":"sip:45962087@192.168.1.127: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" }`| diff --git a/docs/api/peers.md b/docs/api/peers.md new file mode 100644 index 000000000..4e8de582e --- /dev/null +++ b/docs/api/peers.md @@ -0,0 +1,198 @@ +## create + +Creates a new Peer resource. + +**URL** + +`/peers` + +**Method** + +`POST` + +**Parameters** + +This method does not receive any parameters. + +**Request body** + +A file containing an [Peer](/configuration/peer) resource in `json` or `yaml` format. + +**Response** + +If successful this method creates a Peer resource. + +**Sample Call** + +```json +POST /api/{apiversion}/peers +- apiVersion: v1beta1 + kind: Peer + metadata: + name: Asterisk PBX + spec: + credentials: + username: ast + secret: '1234' + +HTTP/1.1 201 Created +{"status": "201", "Successful request"} +``` + +## delete + +Removes a Peer resource from a persistent database. + +**URL** + +`/peers` + +**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 a Peer resource. + +**Sample Call** + +```json +DELETE /api/{apiversion}/peers/{id} +{ + +} + +HTTP/1.1 200 OK +{"status": "200", "Successful request"} +``` + +## get + +This method returns a Peer resource. + +**URL** + +`/peers` + +**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 a Peer resource. + +**Sample Call** + +```json +GET /api/{apiversion}/peers/{id} +{ + +} + +HTTP/1.1 200 OK +{"status": "200", "Successful request"} +``` + +## list + +This method returns a list of Peer resources. + +**URL** + +`/peers` + +**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 Peer resources. + +**Sample Call** + +```json +GET /api/{apiversion}/peers +{ + +} + +HTTP/1.1 200 OK +{"status": "200", "Successful request"} +``` + +## update + +Updates am existing Peer resource. + +**URL** + +`/peer` + +**Method** + +`PUT` + +**Parameters** + +This method does not receive any parameters. + +**Request body** + +A file containing a [Peer](/configuration/peers) resource in `json` or `yaml` format. + +**Response** + +If successful this method updates a Peer resource. + +**Sample Call** + +```json +PUT /api/{apiversion}/peers/{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/registry.md b/docs/api/registry.md new file mode 100644 index 000000000..d55b0970d --- /dev/null +++ b/docs/api/registry.md @@ -0,0 +1,37 @@ +Gets a list of gateways the server is registered on. + +**URL** + +`/registry` + +**Method** + +`GET` + +**Parameters** + +This method does not receive any parameters. + +**Request body** + +Do not supply a request body with this method. + +**Response** + +This method returns a list with registered devices. + +**Sample Call** + +```json +GET /api/{apiversion}/registry +{ + +} + +HTTP/1.1 200 OK +{ + "status":200, + "message":"Successful request", + "result":[] +} +``` diff --git a/mkdocs.yml b/mkdocs.yml index c186a856c..a216997e4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,18 +37,17 @@ nav: - Web Console: administration/webconsole.md - Rest API: - Overview: api/overview.md - - API Permissions: api/api-permissions.md - - Admin APIs: - - Credentials: api/credentials.md - - Location: api/location.md - - Registry: api/registry.md - - Agents: api/agents.md - - Peers: api/peers.md - - Domains: api/domains.md - - Gateways: api/gateways.md - - DIDs: api/dids.md - - System.status: api/system-status.md - - System.info: api/system-info.md + - Credentials: api/credentials.md + - Location: api/location.md + - Registry: api/registry.md + - Agents: api/agents.md + - Peers: api/peers.md + - Domains: api/domains.md + - Gateways: api/gateways.md + - DIDs: api/dids.md + - System: + - Status: api/system-status.md + - Info: api/system-info.md - Guides: - Basic Setup: guides/basic-setup.md - Routr as Asterisk frontend: guides/routr-as-asterisk-frontend.md