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.
You can set authorization using OAuth 2.0 but for that you need to take some steps.
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.
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.
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.
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.
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.
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.
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:
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.
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”
curl -H "Authorization: Bearer<access token>" -G -X GET https://oauth.<domain-name>/api/1.0/dal --dataurlencode “q=<question>"
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."}
{"error": "invalid_scope"}
{"error": "invalid_client"}
The functionality of the parser layer is to change the human language into a logical representation for the system to understand.
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
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.
The functionality of data access layer is to get the parser response and generate dynamic queries in return.
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”
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.
There are three modules of the utils.
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
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)
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.
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.
The functionality of presentation layer is to process the DAL response and generate a suitable visualization in return.
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’
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.