Introduction

This document summaries the usage of the APIs developed by the Quarrio. We have created our own OAuth2 server via which client can access our APIs but for that it is significant to understand the entire procedure. This document will provide proper step by step guide to the user for accessing our different APIs.

1.0 OAuth 2.0

You can set authorization using OAuth 2.0 but for that you need to take some steps.

Getting Started

1.1 Sign Up

Firstly Sign up, if you haven’t done that before.

For sign up you can go to the URL: https://oauth.<domain-name>/signup

To successfully sign up it is necessary to fill up the following credentials in prescribed format.

Example

Username: abc
Email: abc@gmail.com
Password: abcde123

Current Password Policy: minimum 8 characters with a combination of numeric characters and alphabets

Password Confirmation: abcde123

When you have entered all required information, just click on the “Sign up” button to successfully register.

After clicking on “Sign up” button you will receive a verification email on your mentioned email address. If you want to proceed to login, first you have to verify the email.

Note: Email and Username needs to be unique for every account.

1.2 Login

If you have already registered before and verified the email than just go to the login page.

For login you can go to the URL: https://oauth.<domain-name>/accounts/login/

After getting redirected to the above mentioned URL, you can simply add the following credentials to login.

Example

Username: abc
Password: abcde123

When you have filled the mentioned credentials, just click on the “login” button to successfully login.

Note: : In case you haven’t registered before or you have not verified the email address, you will not be able to login.

1.3 Register new applications

After successfully login, you are just few steps away from registering your new application.

If you have registered your applications before, you can get the list of them.

To get the list of registered applications you can go to the URL:
     https://oauth.<domain-name>/api/o/applications/

To register your new application go to the URL:
     https://oauth.<domain-name>/api/o/applications/register/

To register a new application it is necessary to fill in the following credentials.

Example

Name: abcd (Name of the Application)
Client id (generated automatically)
Client secret (generated automatically)

Client type: Confidential
     Confidential: username & password will not be stored on the device you are using, instead temporary tokens are used.

Authorization Grant Type: Resourced owner password-based
     Resourced owner password-based: This type is used by first-party clients to exchange user’s credentials for an access token.

Redirect URI: https://www.xyz.com/
     (You can add the website here where you want to be redirected and receive access code)

After filling in all required information, just click on the “save” button to register the application.

1.4 Request for tokens

After registering your application successfully, a request could be made to get the (new) access tokens.

Note: the commands given below are only applicable for “Curl” but you can also use Postman for performing these steps

CURL command:

URL: https://oauth.<domain-name>/api/o/token/
Request Type: POST
Request Parameters: (grant type, username, password)
Curl command:

Example

curl –X POST –d "grant_type=<granttype>&username=<username>&password=<password>&scope=read"-u "<client_id>:<client_secret>"

https://oauth.<domain-name>/api/o/token/

-d: this tag represents the body of the request
Username = abc
Password = abcde123
Scope as mentioned is the read only
-u: the user authentication tag
Client_id: the token generated by the system when registering the application

Sample: (vsiqwLya7KBghuWopMXfhmd37OW5FfYjMJHiWoWw)
Client_secret: the token generated by the system when registering the application

Sample:
(kk3HKWXBPi27SeJOLxNqH4Ptew9n6LRVqU0Dv9nzHVaaG5hwOfhGH1NjNQ26FC2Mbk9nr9yjNVNPTa8a1JituoY5GJkExxc0GLcxcYiCcKoaZeAXZbSHKqP2HLmnWY8)

Using python Requests library:

1 import requests
2  
3 url = 'https://oauth.<domain-name>/api/o/token/'
4 params = {}
5 params['grant_type'] = 'password'
6 params['username'] = 'your username'
7 params['password'] = 'your password'
8 params['client_id'] = 'your client id'
9 params['client_secret'] = 'your client secret'
10  
11 requests.post(url, params=params)

After processing the given request you will get the following response in return

{"access_token" : <access token>, "expires_in": 36000, "token_type": "Bearer", "scope": "read","refresh_token": <refresh token>}

Access_token: this token can be used to access an API
Expires_in: this shows the expiry date of the access token
Scope: read only
Refresh_token: this token can be used to obtain a renewed access token

The expiry date of the access token is approximately 36000 seconds (24 hrs) whereas the refresh token will expire after 6 months.

After expiry of the refresh token you can again repeat the steps to get a new token.

Using APIs:

DAL

To get to the “Data Access Layer” (DAL), you can use the following request

URL: https://oauth.<domain-name>/api/1.0/dal?q
Request Type: GET
Request Header: Authorization (key: Authorization & value: Bearer <access token> )
Request Parameters: ‘q’ (Question): can be any question for example “how many accounts do I have”

Example

curl -H "Authorization: Bearer<access token>" -G -X GET https://oauth.<domain-name>/api/1.0/dal --dataurlencode “q=<question>"

1.5 Exceptions

There are some exceptions which may occur if something is wrong or invalid.

In case of invalid credentials

{"error": "invalid_grant", "error_description": "Invalid credentials given."}


In case of invalid scope

{"error": "invalid_scope"}


In case client id or secret

{"error": "invalid_client"}

2.0 Parser

2.1 Description

The functionality of the parser layer is to change the human language into a logical representation for the system to understand.

2.2 Access to Parser

To get to the parser layer you can use the following request

URL: https://parser.<domain-name>/open?t=1&s=10&id=782&q

Request Type: GET

Request Parameters Compulsory: ‘q’, ‘id’; q (Question): can be any question for example “how many accounts do I have”; id (ID): this represents the user id (we can get user id from database)

Request Parameters Optional: ‘T’ , ’S’; T (Tree): the tree of parsed question, when t=1, the tree is displayed otherwise the normal parser response is printed; S (Spell Correction): Depends on the user rather he wants to use it or not

2.3 Parser Layer Response

Axioms: Show the formal representation of the response.

Status: show that the parser response is correct or not

Status = Ok (correctly parsed)
Status = Parser error (correctly not parsed any word doesn’t exist in grammar or sentence structure is not understandable)

Output Type: it represents what the user requested, for example a table, bar chart etc.
Parser Tree: shows the structure of the tree and how the question is breakdown in the parser.
Corrected Version: Used for spell correction or to indicate whether any change is in the question was made.

Is Anaphora: is a question related to a previous question. It can be true or false.

3.0 Data Access Manager

3.1 Description

The functionality of data access layer is to get the parser response and generate dynamic queries in return.

3.2 Access to Data Layer

To get to the data access layer you can use the following request

URL: https://dal.<domain-name>/rest/dal?q
Request Type: GET
Request Parameters: ‘q’; q (Question): can be any question for example “how many accounts do I have”

3.3 Data Access Layer Responses

SQL: Return query on the basis of question
Status: there is one further tag in status with two possible values

hasException = false (the query generated is correct)
hasExecption = true (the query generated is not correct, there is some issue)

If hasException = true than further

Reason = Dal Error / Parser Error

If it is Dal Error than it means parser response is not valid or there is issue in dal processing.
If it is Parser Error than it means that the question asked by the user is not understandable for our domain.

Column definition contain the set of fields that user want to see
Multiview: this represents that rather there is more than one query for the question asked by the user or not.

multiview = false (there is only one query for a question)
multiview = true (there is more than one query for a question)

Number of Dataobj : this represents the no of queries.

4.0 Utils:

4.1 Modules of Utils

There are three modules of the utils.

Text Prediction

In this module a neural network model is trained to answer the Salesforce standard schema related questions.

To use this you can use the following request

URL: https://utils.<domain-name>/text/rest/?t=how%20many
Request Type: GET
Accepted Language: English

ASR (Automatic Speech Recognition)

In this module the system will recognize the speech of the user and will answer the asked question.

To use this you can use the following request

URL: https://utils.<domain-name>/speech/rest/
Request Type: POST
Headers: (format, rate, language)
Format (FLAC or WAV)
Language (Default is en-US; option: Chinese-mandarin)
Rate (default 16000)
Body: Audio (audio file)

Example (using curl)

curl -H "format: wav" -H "language: en-US" -H "rate: 16000" -F
audio=@"/home/google/recordings/nonoise.wav" -X POST

At the backend Google cloud speech api is used.

Geo Location:

In this module user will get all cities in a given radius.

To use this you can use the following request

URL: https://utils.<domain-name>/geo/rest/?address=chicago&distance=300
Request Type: GET
Parameter: (Name of city, distance (radius))

At the backend Google Api’s are used which includes geo api and geonames.

5.0 Presentation Layer

5.1 Description

The functionality of presentation layer is to process the DAL response and generate a suitable visualization in return.

5.2 Access to Presentation Layer

To get to the data access layer you can use the following request

URL: URL: https://visual.<domain-name>/api/v/1/visualisation/?convid
Request Type: POST
Request Parameters: ‘convid’

5.3 Presentation Layer Response

There are multiple types of responses which you can get in return.

Renders charts based on the rule sets, rule sets depends the output type, column definition and structure of the dataset provided by DAL.

Presentation layer is currently supporting the following visualizations.

Bar
Pie
Line
Multi line series
Bubble plot
Circle packed charts
Column charts
Multi series column chart
Trend charts
Funnel report
Geographical representation for US states.