doc: Add API example to documentation

README.md

@@ -5,31 +5,7 @@ Proxy that provides access to the VNC console of a Kubevirt VM.
 It can generate time limited tokens that are then used to access VNC.
 
 ## API
-
-### Generate a token
-A temporary token can be generated using:
-```
-GET /api/v1alpha1/${VMI_NAMESPACE}/${VMI_NAME}/token
-``` 
-Where `${VMI_NAMESPACE}` and `${VMI_NAME}` are the namespace
-and name of a running VMI.
-
-Parameters:
-- `duration` - Duration while the token is valid
-
-Headers:
-- `Authorization` - Contains Bearer token that is used to check
-  RBAC permissions to access `/vnc` subresource on a VMI
-
-### Access VNC
-VNC can be accessed using websocket on this endpoint:
-```
-/api/v1alpha1/${VMI_NAMESPACE}/${VMI_NAME}/vnc
-```
-
-This subprotocol is used for authorization:
-- `base64url.bearer.authorization.k8s.io.${TOKEN}` - The `${TOKEN}`
-   is a token generated by the above endpoint.
+See the [API documentation](docs/api.md).
 
 ## Exposing the service
 

docs/api.md

@@ -0,0 +1,52 @@
+# API
+
+The commands in this document use environment variable `PROXY_URL`,
+which should be set to the URL where the `vm-console-proxy` service is
+exposed to the outside of the cluster.
+
+## Generate a token
+
+A temporary token can be generated using:
+```
+GET /api/v1alpha1/${VMI_NAMESPACE}/${VMI_NAME}/token
+``` 
+Where `${VMI_NAMESPACE}` and `${VMI_NAME}` are the namespace
+and name of a running VMI.
+
+#### Parameters
+- `duration` - Duration while the token is valid
+
+#### Headers
+- `Authorization` - Contains Bearer token that is used to check
+  RBAC permissions to access `/vnc` subresource on a VMI
+
+#### Result
+Result is a JSON object containing the token:
+```json
+{ "token": "eyJhb..." }
+```
+
+### Example
+```bash
+curl --header "Authorization: Bearer ${KUBERNETES_USER_TOKEN}" \
+     "https://${PROXY_URL}/api/v1alpha1/${VMI_NAMESPACE}/${VMI_NAME}/token?duration=${DURATION}"
+```
+
+The `KUBERNETES_USER_TOKEN` variable is a bearer token used to authenticate with
+kubernetes API. It can be obtained using:
+```bash
+KUBERNETES_USER_TOKEN=$(oc whoami -t)
+```
+
+## Accessing VNC
+VNC can be accessed using websocket on this endpoint:
+```
+/api/v1alpha1/${VMI_NAMESPACE}/${VMI_NAME}/vnc
+```
+
+#### Subprotocol
+- `base64url.bearer.authorization.k8s.io.${TOKEN}` - Is used for authorization. The `TOKEN`
+   variable is a token generated by the `/token` endpoint.
+
+### Example
+The `example-client` subdirectory shows how to access this endpoint using the [noVNC](https://novnc.com/info.html) JavaScript library.