REST API

Here we present the endpoints available on running NLIs. These endpoints return JSON expressions that represent table and list answers as well as a special choice list which lets users pick the proper interpretation of their question in case of ambiguity. There is also a simple endpoint to generate fresh session identifiers to track concurrent dialogues. The table below presents these endpoints. The python code at the bottom of this file shows this API being called for an example of the D & D NLI running at proxy port 8005 on https://c-phrase.com.

Endpoints

Method Endpoint Purpose Return Type
GET /c-phrase/v1/session Gets a new session id. session
GET /c-phrase/v1/request?session={int}&text={text} Asks the NLI to answer the given question text within the specified session. table-answer, list-answer, choice-list or error
GET /c-phrase/v1/choice?session={int}&choice={int} Chooses the n-th interpretation of the previous choice list within the given session. table-answer, list-answer or error
GET /c-phrase/v1/completions Return a list of tokens that could be used for search bar completions. token-list

Return Types

All returned results are JSON expressions. In the examples below access the d_and_d NLI running on port 8005 of the host https://c-phrase.com. If you paste these examples into your browser's address bar or postman, they should work.

Session

Sessions are integer ids that keep track of specific ongoing dialogues. There can be multiple concurrent sessions.

Table Answer

Table answers either are returned as a direct result of a request, or as the result of choosing an interpretation within a choice list (see below)

List Answer

List answers are similar to table answers, but they are over a single column:

Choice List

A choice list gives all the interpretations for an ambiguous question. Immediately after a choice list is returned, then one of the interpretations may be picked on the next call via the choice endpoint. This in turn will generate a table answer, a list answer or, possibly, an error.

Available Token List

This returns the list of tokens that your application might want to do use in composing questions.

Error

Errors are returned when something fails.

Calling the REST API from Python

This performs the examples above plus a final 'bar chart example' called from python for the D&D NLI running at proxy port 8005 at https://c-phrase.link. We shall leave the D&D NLI running, so executing this code in a python console should work. Note the use of the /api/csrf route to obtain a csrf_token and then /api/login route to authenticate under that token. Subsequent calls then use the authenticated token. The D&D NLI is open to the world, so this is not required. But if D&D were to run requiring a password, then it would be. 

import requests
import json

host = 'https://c-phrase.com:8005'

auth = {
    'username':'rest-test',
    'password':'Mongoose-123'
}

s = requests.Session()
csrf_token = s.get(host + '/api/csrf').text

h = {'X-CSRFToken': csrf_token}

response = s.post(host + '/api/login', headers=h, json=auth)
session = json.loads(s.get(host + "/c-phrase/v1/session", headers=h).text)['session']

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=lawful evil dragons with more than 300 hit points", headers=h).text)
print(answer['table-answer']['sql'])

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=names of Chaotic Good or Chaotic Neutral Feys", headers=h).text)
print(answer['list-answer']['paraphrase'])

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=average strength of fiends", headers=h).text)
print(answer['table-answer']['paraphrase'])

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=Dragons taking non-standard damage", headers=h).text)
if 'choices' in answer:
    answer = json.loads(s.get(host + f"/c-phrase/v1/choice?session={session}&choice=2", headers=h).text)
    print(answer['table-answer']['rows'][0]['monster'])

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=saskwatch", headers=h).text)
print(answer['error']['message'])

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=how many monsters per type", headers=h).text)
print(answer['table-answer']['type'])

answer = json.loads(s.get(host + f"/c-phrase/v1/completions", headers=h).text)
print(answer)