updated api guide

docs/api.rst

@@ -2,7 +2,10 @@
 Using sentinel APIs
 ===================
 
-Sentinel monitoring exposes a rich set of APIs for user and space management. The current release of sentinel has APIs supporting bare-minimal features and as the features set get richer, so will be the APIs. Below are the list of APIs currently offered by the framework -
+Sentinel monitoring exposes a rich set of APIs for user and space management. 
+The current release of sentinel has APIs supporting bare-minimal features and 
+as the features set get richer, so will be the APIs. Below are the list of 
+APIs currently offered by the framework -
 
 * /v1/api/ - shows list of supported APIs
 * /v1/api/user/ - everything to do with user management
@@ -14,9 +17,13 @@ Sentinel monitoring exposes a rich set of APIs for user and space management. Th
 Key concepts
 ============
 
-**Space**: Think of it as a collection of metrics belonging to different streams but somehow belonging to the same scope, application or service. A space could be allocated to metrics of smaller services making up a larger application or service.
+**Space**: Think of it as a collection of metrics belonging to different 
+streams but somehow belonging to the same scope, application or service. A 
+space could be allocated to metrics of smaller services making up a larger 
+application or service.
 
-**Series**: A series in Sentinel is a stream of metrics coming from the same source.
+**Series**: A series in Sentinel is a stream of metrics coming from the same 
+source.
 
 API return codes at a glance
 ============================
@@ -109,11 +116,15 @@ Header fields at a glance
 
 APIs in details
 ===============
-Now that we have all the basic building buildings in place, lets explore each API endpoint in more details. In the following subsections lets assume that the sentinel API service is available at https://localhost:9000/. Also API example will be provided as a valid cURL command.
+Now that we have all the basic building buildings in place, lets explore each 
+API endpoint in more details. In the following subsections lets assume that 
+the sentinel API service is available at https://localhost:9000/. Also API 
+example will be provided as a valid cURL command.
 
 /v1/api/ GET
 ------------
-This API allows a quick check on the health status, if the service is alive a 200 status code is returned along with a list of supported API endpoints.
+This API allows a quick check on the health status, if the service is alive a 
+200 status code is returned along with a list of supported API endpoints.
 
 ::
 
@@ -164,21 +175,38 @@ The response is similar to one shown below -
      "method": "GET",
      "description": "retrieve the agent's connection endpoint parameters",
      "contentType": "application/json"
-   }
+   },
+   {
+        "endpoint": "/v1/api/pingback/{id}",
+        "method": "GET",
+        "description": "retrieve the healthcheck/pingback object data",
+        "contentType": "application/json"
+    },
+    {
+        "endpoint": "/v1/api/pingback/",
+        "method": "POST",
+        "description": "registers a new healthcheck/pingback object",
+        "contentType": "application/json"
+    }
   ]
 
-The output above is representative, and the actual API supported by sentinel varied during the time of writing of this document.
+The output above is representative, and the actual API supported by sentinel 
+varied during the time of writing of this document.
 
 /v1/api/user/ POST
 ------------------
-Use this API to create a new user of sentinel. User account creation is an admin priviledged operation and the *admin-token* is required as header for the call to be executed successfully.
+Use this API to create a new user of sentinel. User account creation is an 
+admin priviledged operation and the *admin-token* is required as header for 
+the call to be executed successfully.
 
 ::
 
   curl -X POST https://localhost:9000/v1/api/user/ --header "Content-Type: application/json" 
   --header "x-auth-token: <admin-token>" -d '{"login":"username", "password":"some-password"}'
 
-If the user already exists, you will get a *409 Conflict* status response back. An example response upon successful creation of an account looks as shown below, the actual value is for representation purposes only -
+If the user already exists, you will get a *409 Conflict* status response 
+back. An example response upon successful creation of an account looks as 
+shown below, the actual value is for representation purposes only -
 
 ::
 
@@ -189,18 +217,22 @@ If the user already exists, you will get a *409 Conflict* status response back.
     "accessUrl": "/api/user/2"
   }
 
-The *apiKey* and *id* values should be saved as they are needed in some of the management API requests as you will see later.
+The *apiKey* and *id* values should be saved as they are needed in some of the 
+management API requests as you will see later.
 
 /v1/api/user/{id} GET
 ---------------------
-Use this API to retrieve the complete information about an user account, the monitoring spaces and series info included. A valid *api-key* needs to be provided as a header field while making this call.
+Use this API to retrieve the complete information about an user account, the 
+monitoring spaces and series info included. A valid *api-key* needs to be 
+provided as a header field while making this call.
 
 ::
 
   curl -X GET https://localhost:9000/v1/api/user/{id} --header "Content-Type: application/json"
   --header "x-auth-apikey: valid-api-key"
 
-If the call succeeds then the complete details of the account is returned back. A sample value returned is shown next.
+If the call succeeds then the complete details of the account is returned 
+back. A sample value returned is shown next.
 
 ::
 
@@ -231,15 +263,19 @@ If the call succeeds then the complete details of the account is returned back.
 
 /v1/api/space/ POST
 -------------------
-Use this API to create a new monitored space for a given user account in sentinel. A matching *username* and the *api-key* needs to be provided as header fields. The body just contains the *name* of the space that one wishes to create.
+Use this API to create a new monitored space for a given user account in 
+sentinel. A matching *username* and the *api-key* needs to be provided as 
+header fields. The body just contains the *name* of the space that one wishes 
+to create.
 
 ::
 
   curl -X POST https://localhost:9000/v1/api/space/ --header "Content-Type: application/json"
   --header "x-auth-login: username" --header "x-auth-apikey: some-api-key"
   -d '{"name":"space-name"}'
 
-If the call is successful, the *space id* is returned back as confirmation. A sample response is shown next.
+If the call is successful, the *space id* is returned back as confirmation. A 
+sample response is shown next.
 
 ::
 
@@ -255,17 +291,23 @@ If the call is successful, the *space id* is returned back as confirmation. A sa
 
 /v1/api/series/ POST
 --------------------
-A space by itself does not handle data streams, it is a container and needs a series to be defined before the metrics sent to it can be persisted and analyzed later. This API allows creation of a *series* within an existing *space*. The *msgSignature* allows sentinel to parse the incoming messages properly. 
+A space by itself does not handle data streams, it is a container and needs a 
+series to be defined before the metrics sent to it can be persisted and 
+analyzed later. This API allows creation of a *series* within an existing 
+*space*. The *msgSignature* allows sentinel to parse the incoming messages 
+properly. 
 
-If the message being sent into sentinel is a single level JSON string, the *unixtime:s msgtype:json* value is sufficient.
+If the message being sent into sentinel is a single level JSON string, the 
+*unixtime:s msgtype:json* value is sufficient.
 
 ::
 
   curl -X POST https://localhost:9000/v1/api/series/ --header "Content-Type: application/json"
   --header "x-auth-login: username" --header "x-auth-apikey: some-api-key"
   -d '{"name":"series-name", "spaceName":"parent-space-name", "msgSignature":"msg-signature"}'
 
-If the call is successful, a *series id* is returned. An example response block is shown for completeness.
+If the call is successful, a *series id* is returned. An example response 
+block is shown for completeness.
 
 ::
 
@@ -277,15 +319,18 @@ If the call is successful, a *series id* is returned. An example response block
 
 /v1/api/key/{id} GET
 --------------------
-One can use this API if there is a need to retrieve the user api-key. The *username* should be a registered account and the *some-password* header field should be the matching password for this account.
+One can use this API if there is a need to retrieve the user api-key. The 
+*username* should be a registered account and the *some-password* header field 
+should be the matching password for this account.
 
 ::
 
   curl -X GET https://localhost:9000/v1/api/key/{username} 
   --header "Content-Type: application/json"
   --header "x-auth-password: some-password"
 
-If the call is successful, the API-key is returned. A sample response is shown next.
+If the call is successful, the API-key is returned. A sample response is shown 
+next.
 
 ::
 
@@ -297,14 +342,18 @@ If the call is successful, the API-key is returned. A sample response is shown n
 
 /v1/api/endpoint GET
 --------------------
-This API call can be used to retrieve the connection parameters for the sentinel agents to send data streams to. The call is available only to registered accounts, therefore a valid *username* and *api-key* needs to be supplied as header fields.
+This API call can be used to retrieve the connection parameters for the 
+sentinel agents to send data streams to. The call is available only to 
+registered accounts, therefore a valid *username* and *api-key* needs to be 
+supplied as header fields.
 
 ::
 
   curl -X GET https://localhost:9000/v1/api/endpoint --header "Content-Type: application/json"
   --header "x-auth-login: username" --header "x-auth-apikey: some-api-key"
 
-If the call succeeds, the parameter block is returned that can be used to properly configure the sentinel agents. A sample response is shown next.
+If the call succeeds, the parameter block is returned that can be used to 
+properly configure the sentinel agents. A sample response is shown next.
 
 ::
 
@@ -316,9 +365,13 @@ If the call succeeds, the parameter block is returned that can be used to proper
 
 /v1/dashboard/ GET
 ------------------
-This API call can be used to get the Grafana dashboard as an embedded iFrame from the sentinel framework. One may need to login into the dashboard using the Grafana account credentials. This API call is not authenticated. Authentication is enforced by Grafana.
+This API call can be used to get the Grafana dashboard as an embedded iFrame 
+from the sentinel framework. One may need to login into the dashboard using 
+the Grafana account credentials. This API call is not authenticated. 
+Authentication is enforced by Grafana.
 
-If the call succeeds, an HTML codeblock is returned which renders the dashboard. A sample response is shown next.
+If the call succeeds, an HTML codeblock is returned which renders the 
+dashboard. A sample response is shown next.
 
 ::
 
@@ -330,7 +383,12 @@ If the call succeeds, an HTML codeblock is returned which renders the dashboard.
 
 /v1/api/pingback/ POST
 ----------------------
-This call is used to register a new pingback entry with sentinel. Think of it as a health check service. It allows one to register an endpoint to be monitored, and if the check fails then a callback to be made to another endpoint. This feature only supports GET calls. The call is available only to registered accounts, therefore a valid *username* and *api-key* needs to be supplied as header fields.
+This call is used to register a new pingback entry with sentinel. Think of it 
+as a health check service. It allows one to register an endpoint to be 
+monitored, and if the check fails then a callback to be made to another 
+endpoint. This feature only supports GET calls. The call is available only to 
+registered accounts, therefore a valid *username* and *api-key* needs to be 
+supplied as header fields.
 
 ::
 
@@ -344,14 +402,22 @@ This call is used to register a new pingback entry with sentinel. Think of it as
     "method":"body,status,up"
   }'
 
-In the call above, **periodicity** is specified as multiples of 30 seconds in nanoseconds, **toleranceFactor** is the number of successive failed checks that will trigger a callback to the **reportURL** endpoint. Currently only two **methods** are supported -
+In the call above, **periodicity** is specified as multiples of 30 seconds in 
+nanoseconds, **toleranceFactor** is the number of successive failed checks 
+that will trigger a callback to the **reportURL** endpoint. Currently only two 
+**methods** are supported -
 
 * code - the HTTP response code is the sole criteria for success or failure
-* body,{field},{intended value} - in this mode, the response body is treated as a JSON value, and **{field}** specifies the JSON field to be checked for the value specified by **{intended value}** field. If the defined value is not found, it is treated as a failure condition.
+* body,{field},{intended value} - in this mode, the response body is treated 
+as a JSON value, and **{field}** specifies the JSON field to be checked for 
+the value specified by **{intended value}** field. If the defined value is not 
+found, it is treated as a failure condition.
 
-Note: since comma (,) is used as a separator character, **{field}** and **{intented value}** parameters must not contain a comma (,) in them.
+Note: since comma (,) is used as a separator character, **{field}** and 
+**{intented value}** parameters must not contain a comma (,) in them.
 
-If the call succeeds, the details of the registered pingback endpoint is returned. An example response is shown next -
+If the call succeeds, the details of the registered pingback endpoint is 
+returned. An example response is shown next -
 
 ::
 
@@ -367,14 +433,18 @@ If the call succeeds, the details of the registered pingback endpoint is returne
 
 /v1/api/pingback/{id} GET
 -------------------------
-This call allows the user to retrieve the details of a particular pickback object. The call is available only to registered accounts, therefore a valid *username* and *api-key* needs to be supplied as header fields.
+This call allows the user to retrieve the details of a particular pickback 
+object. The call is available only to registered accounts, therefore a valid 
+*username* and *api-key* needs to be supplied as header fields.
 
 ::
 
   curl -X GET http://localhost:9000/v1/api/pingback/1 \
   -H 'x-auth-apikey: some-api-key' -H 'x-auth-login: some-username'
 
-If the API call is successful, the details of the pingback is returned along with last 10 healthcheck results along with the timestamp. An example response is shown nect -
+If the API call is successful, the details of the pingback is returned along 
+with last 10 healthcheck results along with the timestamp. An example response 
+is shown next -
 
 ::