Correct & clarify parts of API spec (#11130)

* update API spec

* update authentication methods section

Co-authored-by: Anca Lita <[email protected]>

* review

* fix json NLU testing evaluation


Co-authored-by: m-vdb <[email protected]>
Co-authored-by: Anca Lita <[email protected]>

changelog/11130.doc.md

@@ -0,0 +1,12 @@
+Clarify aspects of the API spec
+GET /status endpoint: Correct response schema for model_id - a string, not an object.
+
+GET /conversations/{conversation_id}/tracker: Describe each of the enum options for include_events query parameter
+
+POST & PUT /conversations/{conversation_id}/tracker/eventss: Events schema added for each event type
+
+GET /conversations/{conversation_id}/story: Clarified the all_sessions query parameter and default behaviour.
+
+POST /model/test/intents : Remove JSON payload option since it is not supported
+
+POST /model/parse: Explain what emulation_mode is and how it affects response results

docs/docs/http-api.mdx

@@ -50,54 +50,44 @@ The [SocketIO channel](./connectors/your-own-website.mdx#websocket-channel) does
 
 ## Security Considerations
 
-We recommend to not expose the Rasa Server to the outside world, but
-rather connect to it from your backend over a private connection (e.g.
-between docker containers).
+We recommend that you don't expose the Rasa Server to the outside world directly, but
+rather connect to it via e.g. Nginx.
 
 Nevertheless, there are two authentication methods built in:
 
 ### Token Based Auth
 
-Pass in the token using `--auth-token thisismysecret` when starting
+To use a plaintext token to secure your server, specify the token in the argument `--auth-token thisismysecret` when starting
 the server:
 
 ```bash
 rasa run \
-    -m models \
     --enable-api \
-    --log-file out.log \
     --auth-token thisismysecret
 ```
 
-Your requests should pass the token, in our case `thisismysecret`,
-as a parameter:
+Any clients sending requests to the server must pass the token
+as a query parameter, or the request will be rejected. For example, to fetch a tracker from the server:
 
 ```bash
 curl -XGET localhost:5005/conversations/default/tracker?token=thisismysecret
 ```
 
 ### JWT Based Auth
 
-Enable JWT based authentication using `--jwt-secret thisismysecret`.
-Requests to the server need to contain a valid JWT token in
-the `Authorization` header that is signed using this secret
-and the `HS256` algorithm.
+To use JWT based authentication, specify the JWT secret in the argument `--jwt-secret thisismysecret`
+on startup of the server:
 
-The token's payload must contain an object under the `user` key,
-which in turn must contain the `username` and `role` attributes.
-If the `role` is `admin`, all endpoints are accessible.
-If the `role` is `user`, endpoints with a `sender_id` parameter are only accessible
-if the `sender_id` matches the payload's `username` property.
 
 ```bash
 rasa run \
-    -m models \
     --enable-api \
-    --log-file out.log \
     --jwt-secret thisismysecret
 ```
 
-Your requests should have set a proper JWT header:
+Client requests to the server will need to contain a valid JWT token in
+the `Authorization` header that is signed using this secret
+and the `HS256` algorithm e.g.
 
 ```text
 "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ"
@@ -106,6 +96,8 @@ Your requests should have set a proper JWT header:
                  "Gl8eZFVfKXA6jhncgRn-I"
 ```
 
+The token's payload must contain an object under the `user` key,
+which in turn must contain the `username` and `role` attributes.
 The following is an example payload for a JWT token:
 
 ```json
@@ -117,5 +109,16 @@ The following is an example payload for a JWT token:
 }
 ```
 
+If the `role` is `admin`, all endpoints are accessible.
+If the `role` is `user`, endpoints with a `sender_id` parameter are only accessible
+if the `sender_id` matches the payload's `username` property.
+
+```bash
+rasa run \
+    -m models \
+    --enable-api \
+    --jwt-secret thisismysecret
+```
+
 To create and encode the token, you can use tools such as the [JWT Debugger](https://jwt.io/), or a Python module such as [PyJWT](https://pyjwt.readthedocs.io/en/latest/).