Documentation "lacks": confused with RASA NLU/Core HTTP (REST) API doc #5749

solyarisoftware · 2020-04-29T15:42:37Z

Hi all,
I'm new with RASA and reading main user guide https://rasa.com/docs/rasa/, I'm confused with HTTP APIs documentation.

1. RASA NLU API Documentation
Usage is described in page
https://rasa.com/docs/rasa/nlu/using-nlu-only/#running-an-nlu-server
That's pretty minimal but ok.

Suggestions:

1.1 To insert a full example in page Running an NLU server , specifically in this section: https://rasa.com/docs/rasa/nlu/using-nlu-only/#running-an-nlu-server

The example should show full JSON reply to endoint call. That's trivial but immo engage the beginner:

1.2 minor: I'd call explicitly the section NLU API call.

So, to be fully didactic I'd insert something like this, just as an example:

Run the RASA NLU server and Call the RASA NLU endpoint API:

rasa run --enable-api -m models/20200426-234932.tar.gz


$  curl localhost:5005/model/parse -s -d '{ "text": "hello" }' | python -m json.tool
{
    "entities": [],
    "intent": {
        "confidence": 0.9950834513,
        "name": "greet"
    },
    "intent_ranking": [
        {
            "confidence": 0.9950834513,
            "name": "greet"
        },
        {
            "confidence": 0.0024154091,
            "name": "affirm"
        },
        {
            "confidence": 0.0006950966,
            "name": "deny"
        },
        {
            "confidence": 0.0005983639,
            "name": "goodbye"
        },
        {
            "confidence": 0.0005174898,
            "name": "bot_challenge"
        },
        {
            "confidence": 0.0003472178,
            "name": "mood_unhappy"
        },
        {
            "confidence": 0.0002260254,
            "name": "thank"
        },
        {
            "confidence": 0.0001169968,
            "name": "mood_great"
        }
    ],
    "text": "hello"
}

2. RASA Core API Documentation

The endpoint is just mentioned in page with title Your Own Website:
https://rasa.com/docs/rasa/user-guide/connectors/your-own-website/

But I found it hard to discover the page, starting from https://rasa.com/docs/rasa/ page.

Neither I find the API interface description in the API reference page:
https://rasa.com/docs/rasa/api/http-api/

My suggestions :

2.1 I'd name the page https://rasa.com/docs/rasa/user-guide/connectors/your-own-website/#rest-channels with an explicit name as "RASA Core REST API" and I'd mention the page in the main index.
2.2 I'd explode the page https://rasa.com/docs/rasa/user-guide/connectors/your-own-website/#rest-channels giving a full example of usage of webhook endpoint, something like for example:

$ rasa run --enable-api -m models/20200426-234932.tar.gz

$ curl -s localhost:5005/webhooks/rest/webhook -d '{ "sender": "Giorgio", "message": "I am a bit sad"}'  | python -m json.tool
[
    {
        "recipient_id": "Giorgio",
        "text": "Here is something to cheer you up:"
    },
    {
        "image": "https://i.imgur.com/nGF1K8f.jpg",
        "recipient_id": "Giorgio"
    },
    {
        "recipient_id": "Giorgio",
        "text": "Are you feeling better?"
    }
]

2.3 I'd insert all webhook API endpoint details in the HTTP-API page.

Thanks
giorgio

(venv) $ pip3 --version
pip 20.0.2 from /home/solyaris/venv/lib/python3.6/site-packages/pip (python 3.6)
(venv) $ python3 --version
Python 3.6.9
(venv) $ rasa --version
Rasa 1.9.7

solyarisoftware · 2020-04-29T15:45:18Z

BTW, the bug attribute is maybe just related to the lack of webhook endpoint API description in page https://rasa.com/docs/rasa/api/http-api/

sara-tagger · 2020-04-30T06:00:16Z

Thanks for the issue, @rgstephens will get back to you about it soon!

You may find help in the docs and the forum, too 🤗

rgstephens · 2020-05-05T01:11:33Z

@solyarisoftware Thanks for the detailed suggestions.

solyarisoftware · 2020-05-05T10:12:26Z

BTW, rethinking again about how to simplify/clarify RASA HTTP API documentation in general, I believe page https://rasa.com/docs/rasa/api/http-api/ is not fully clear (for beginners at least) and it's partially incomplete, as said.

Here the complete list of available endpoints that rasa run shows:

2020-05-05 09:51:39 DEBUG    rasa.core.utils  - Available web server routes:
/conversations/<conversation_id>/messages          POST                           add_message
/conversations/<conversation_id>/tracker/events    POST                           append_events
/webhooks/rest                                     GET                            custom_webhook_RestInput.health
/webhooks/rest/webhook                             POST                           custom_webhook_RestInput.receive
/model/test/intents                                POST                           evaluate_intents
/model/test/stories                                POST                           evaluate_stories
/conversations/<conversation_id>/execute           POST                           execute_action
/domain                                            GET                            get_domain
/                                                  GET                            hello
/model                                             PUT                            load_model
/model/parse                                       POST                           parse
/conversations/<conversation_id>/predict           POST                           predict
/conversations/<conversation_id>/tracker/events    PUT                            replace_events
/conversations/<conversation_id>/story             GET                            retrieve_story
/conversations/<conversation_id>/tracker           GET                            retrieve_tracker
/status                                            GET                            status
/model/predict                                     POST                           tracker_predict
/model/train                                       POST                           train
/conversations/<conversation_id>/trigger_intent    POST                           trigger_intent
/model                                             DELETE                         unload_model
/version                                           GET                            version

What I propose to improve docs is a https://rasa.com/docs/rasa/api/http-api/ page rescope, as the list of available endpoints, with these possible attributes for each endpoint:

1. Functional name 
    e.g. `model/parse` as the RASA NLU message intent/entities classification. 
    e.g.  `/webhooks/rest/webhook` as the RASA Core Dialog Manager output
    etc.

2. Typical usage
    e.g. Specifying the reason why of the endpoint, application side. The possible phase (train/test/runtime). The possible flow. E.g. At run-time I would call /conversations/<conversation_id>/tracker after a /webhooks/rest/webhook, to get the intent corresponding to an input message, etc.

3. HTTP call details 
  e.g. the URL,HTTP method (POST, GET, etc,) input parameters details, output JSON payload, HTTP error codes  

4. Usage example 
    e.g. using `curl`

That's just an hypothesis.

Because I'm beginner using RASA, I wouldn't propose myself for the possible update work on documentation, but for sure I'd happy to contribute for a successive user-side testing/verify.

Thanks

solyarisoftware added area:rasa-oss 🎡 type:bug 🐛 labels Apr 29, 2020

rgstephens added type:docs 📖 and removed type:bug 🐛 labels May 5, 2020

RasaHQ / rasa

Documentation "lacks": confused with RASA NLU/Core HTTP (REST) API doc #5749

Documentation "lacks": confused with RASA NLU/Core HTTP (REST) API doc #5749

solyarisoftware commented Apr 29, 2020

solyarisoftware commented Apr 29, 2020

sara-tagger commented Apr 30, 2020

rgstephens commented May 5, 2020

solyarisoftware commented May 5, 2020

RasaHQ / rasa

Join GitHub today

Documentation "lacks": confused with RASA NLU/Core HTTP (REST) API doc #5749

Documentation "lacks": confused with RASA NLU/Core HTTP (REST) API doc #5749

Comments

solyarisoftware commented Apr 29, 2020

solyarisoftware commented Apr 29, 2020

sara-tagger commented Apr 30, 2020

You may find help in the docs and the forum, too 🤗

rgstephens commented May 5, 2020

solyarisoftware commented May 5, 2020