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 Geo NLI running at proxy port 8002 on https://michael.c-phrase.link.

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, assume that the geo NLI is running on port 9000 of the host domain.com.

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. Importantly aggregate function results are lists of length one. See the second example below:

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.

Token List

This returns a list of tokens that your application might want to do completions on.

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 a Geo NLI running at proxy port 8002 at https://michael.c-phrase.link. 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.

We shall leave this NLI running, so executing this code in a python console should work. 

import requests
import json

host = 'https://michael.c-phrase.link:8002'

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=three longest rivers", headers=h).text)
print(answer['table-answer']['sql'])

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

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=largest state", 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]['name'])

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 cities per state", headers=h).text)
print(answer['table-answer']['type'])

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