External API recommendations

Do virtuálního asistenta je možné připravit libovolné množství "integračních kroků", což jsou body konverzačního stromu, kdy se virtuální asistent pomocí API integruje s jiným systémem za účelem získání nějakých dat nutných pro svou funkci nebo naopak nějaká data, která od uživatele zjistil do systému posílá.

Ve formátu a struktuře API se virtuální asistent může poměrně dost přizpůsobit, pokud by ale API vznikalo až kvůli němu, je možné se držet následujících doporučení, aby implementace byla co nejplynulejší.

Doporučené vlastnosti API

• Autentizace ideálně jedním z následujících způsobů
  • username+password jako BASE64 string v hlavičce Authorization: Basic ...
  • token v hlaviččce Authorization: Bearer ... 
    • může být jeden předem daný pro celého virtuálního asistenta
    • nebo pokud bot např. běží uvnitř systému, kam se uživatel přihlašuje, může být tento token předán botovi vždy se scopem daného uživatele, takže bot bude mít maximálně jeho oprávnění a ne vyšší
  • standardní OAuth2 client_credentials grant (tedy separátní požadavek pro získání a prodloužení accces tokenu, který se pak použije v  Authorization: Bearer ... s každým požadavkem
• Ideálně se držet REST pravidel pro používané HTTP metody
  • GET pro získání dat
  • POST pro založení nového záznamu nebo spuštění nějaké akce (není idempotentní)
  • PUT pro aktualizaci existujícího záznamu (jeho identifikátor ideálně jako parametr URL)
  • PATCH pro částečnou aktualizaci existujícího záznamu (jeho identifikátor ideálně jako parametr URL)
  • DELETE pro odstranění existujícího záznamu (jeho identifikátor ideálně jako parametr URL)
• Tělo požadavku i odpovědi jako JSON
• Pokud to daná metoda vyžaduje, filtrování a řazení dat implementovat jako parametry URL adresy, nebo jako vlastní X-... HTTP hlavičky
• Maximální čas odezvy by bylo dobré držet pod 3 sekundami, protože v některých use-casech se API může volat synchronně v reálném čase a uživatel bude na výsledek čekat

Ukázka

Virtuální asistent může pomocí API získat ze závislého systému seznam událostí, které má naplánované. ID uživatele jsou předány např. do WebChat komponenty uvnitř nějakého interního systému, kde je uživatel již autentizován. Data bot využije k zobrazení "carouselu" s naplánovanými událostmi, kde si uživatel jednu z nich může vybrat a pokračovat nějakou další akcí.

GET https://somedomain.cz/api/v1/user/33/events

Authorization: Bearer ...
Content-type: application/json

→ 200 [{"id":"1", "name":"Onboarding meeting", "date":"2020-05-07T08:22:30.871Z"}]

Na konci komunikace může virtuální asistent odeslat informace o nově získaném uživateli do CRM. Součástí požadavku můžou být všechna data, která virtuální asistent o uživateli posbíral.

POST https://somedomain.cz/api/v1/user

Authorization: Bearer ...
Content-type: application/json
{"email": "user@example.com", "name":"Jack", "surname":"User", "interestedInProductIds": [244, 234]}

→ 200 {"id":"433"}