update readme

httphandler/README.md

@@ -1,26 +1,85 @@
 # Kubescape HTTP Handler Package
 
-> This is a beta version, we might make some changes before publishing the official Prometheus support
-
-Running `kubescape` will start up a webserver on port `8080` which will serve the following paths: 
+Running `kubescape` will start up a webserver on port `8080` which will serve the following API's: 
 
 ### Trigger scan
 
-* POST `/v1/scan` - Trigger a kubescape scan. The server will return an ID and will execute the scanning asynchronously 
-* * `wait=true`: scan synchronously (return results and not ID). Use only in small clusters are with an increased timeout. default is `wait=false`
-* * `keep=true`: Do not delete results from local storage after returning. default is `keep=false`
+* POST `/v1/scan` - trigger a kubescape scan. The server will return an ID and will execute the scanning asynchronously. the request body should look [as followed](#trigger-scan-object).
+* * `wait=true`: scan synchronously (return results and not ID). Use only in small clusters or with an increased timeout. default is `wait=false`
+* * `keep=true`: do not delete results from local storage after returning. default is `keep=false`
+* POST `/v1/metrics` - trigger kubescape for Prometheus support. [read more](examples/prometheus/README.md)
+
+[Response](#response-object):
+
+```
+{
+  "id": <str>,                      // scan ID
+  "type": "busy",                   // response object type
+  "response": <message:string>      // message indicating scanning is still in process
+}
+```
+
+> When scanning was triggered with the `wait=true` query param, the response is like the [`/v1/results` API](#get-results) response
 
 ### Get results
-* GET `/v1/results` -  Request kubescape scan results
-* * query `id=<string>` -> ID returned when triggering the scan action. If empty will return latest results
-* * query `keep=true` -> Do not delete results from local storage after returning. default is `keep=false`
+* GET `/v1/results` -  request kubescape scan results
+* * query `id=<string>` -> request results of a specific scan ID. If empty will return latest results
+* * query `keep=true` -> keep the results in the local storage after returning. default is `keep=false` - the results will be deleted from local storage after they are returned
 
+[Response](#response-object):
+
+When scanning was done successfully
+```
+{
+  "id": <str>,                      // scan ID
+  "type": "v1results",              // response object type
+  "response": <object:v1results>    // v1 results payload
+}
+```
+
+When scanning failed
+```
+{
+  "id": <str>,                  // scan ID
+  "type": "error",              // response object type
+  "response": <error:string>    // error string
+}
+```
+
+When scanning is in progress
+```
+{
+  "id": <str>,                    // scan ID
+  "type": "busy",                 // response object type
+  "response": <message:string>    // message indicating scanning is still in process
+}
+```
 ### Check scanning progress status
 Check the scanning status - is the scanning in progress or done. This is meant for a waiting mechanize since the API does not return the entire results object when the scanning is done
 
 * GET `/v1/status` -  Request kubescape scan status
 * * query `id=<string>` -> Check status of a specific scan. If empty will check if any scan is in progress
 
+[Response](#response-object):
+
+When scanning is in progress
+```
+{
+  "id": <str>,                    // scan ID
+  "type": "busy",                 // response object type
+  "response": <message:string>    // message indicating scanning is still in process
+}
+```
+
+When scanning is not in progress
+```
+{
+  "id": <str>,                    // scan ID
+  "type": "notBusy",              // response object type
+  "response": <message:string>    // message indicating scanning is done in process
+}
+```
+
 ### Delete cached results
 * DELETE `/v1/results` - Delete kubescape scan results from storage. If empty will delete latest results
 * * query `id=<string>`: Delete ID of specific results 
@@ -32,10 +91,10 @@ Check the scanning status - is the scanning in progress or done. This is meant f
 * `/livez` - will respond 200 is server is alive
 * `/readyz` - will respond 200 if server can receive requests 
 
-## Trigger Kubescape scan
+## Objects
+
+### Trigger scan object
 
-POST /v1/scan
-body:
 ```
 {
   "format": <str>,               // results format [default: json] (same as 'kubescape scan --format')
@@ -51,7 +110,8 @@ body:
 }
 ```
 
-Response body:
+### Response object
+
 ```
 {
   "id": <str>,                      // scan ID
@@ -59,10 +119,12 @@ Response body:
   "response": <object:interface>    // response payload as list of bytes
 }
 ```
+#### Response object types
 
-Response body types:
 *  "v1results" - v1 results object
-*  "id" - id string
+*  "busy" - server is busy processing previous requests 
+*  "notBusy" - server is not busy processing previous requests
+*  "ready" - server is done processing request and results are ready  
 *  "error" - error object
 
 ## API Examples

httphandler/examples/prometheus/README.md

@@ -110,13 +110,4 @@ kubescape_control_count_resources_excluded{name="<control name>",url="<docs url>
 kubescape_control_count_resources_passed{name="<control name>",url="<docs url>",severity="<control severity>"} <counter>
 ```
 
-#### Resources metrics
-The resources metrics give you the ability to prioritize fixing the resources by the number of controls that failed 
-
-```
-# Number of controls that failed for this particular resource
-kubescape_resource_count_controls_failed{apiVersion="<>",kind="<>",namespace="<>",name="<>"} <counter>
-
-# Number of controls that where excluded for this particular resource
-kubescape_resource_count_controls_excluded{apiVersion="<>",kind="<>",namespace="<>",name="<>"} <counter>
-```
+ 

httphandler/handlerequests/v1/requestshandler.go

@@ -148,8 +148,8 @@ func (handler *HTTPHandler) Results(w http.ResponseWriter, r *http.Request) {
 
 	if resultsQueryParams.ScanID == "" { // if no scan found
 		logger.L().Info("empty scan ID")
-		w.WriteHeader(http.StatusBadRequest) // Should we return ok?
-		response.Response = "latest scan not found. trigger again"
+		w.WriteHeader(http.StatusBadRequest)
+		response.Response = "latest scan not found"
 		response.Type = utilsapisv1.ErrorScanResponseType
 		w.Write(responseToBytes(&response))
 		return