What is REST API?
REST API – REpresentational State Transfer Application Program Interface.
Representational State Transfer is an architectural style for exposing your program using existing protocols, typically HTTP, to GET, POST, PUT, and DELETE Data.
How does REST API work?
A REST API breaks down a transaction to create a series of small modules. Each module addresses an underlying part of the transaction.
A REST API uses:
GET to retrieve a resource.
POST to create a resource.
PUT to change the state of, or update a resource, which can be an object, file or block.
DELETE to remove a resource.
The following sections show how to use the APIs, using “Intent Manager” APIs as examples.
Get Authorization Keys
A developer should have an Orbita user’s login credentials to access APIs and call the following API to get the bearer’s token.
/api/login
If the credentials are correct, the response from the API will be a JW token, which is the bearer’s token for the request.
The bearer’s token is passed through the Authorization property in the Request Header of subsequent API requests.
The minimum validity for the JW token is 4 hours.
If JW token is expired, the application must call for JW token again.
The Content-Type property in the Request Header will be application/json.
GET
Sends a simple request to read a response from the remote server.
Get all intents
Get a specific intent
Get the list of all intents
To get a list of all the available intents in the current server, use the following API call:
/api/voice/intent
Example usage
curl. Client’s URL.
curl -X PATCH http://[YOUR_ENDPOINT]/api/voice/intent
PATCH Example
{
"page": 1,
"limit": 10,
"strictProject": true,
"q": {
"projectId": "597b029b93077c05214403be",
"condition": {
"isDeleted": false,
"name": "intentname"
}
}
}
Success Response
HTTP/1.1 200 OK
{
"pageData": [
{
"_id": "599ed51e7abba31e4ab1237b",
"modifiedAt": "2017-08-24T13:31:10.707Z",
"name": "testemptyslotarray3",
"createdBy": "5971f9f8328af5c9637958b3",
"isDeleted": false,
"createdAt": "2017-08-24T13:31:10.707Z",
"projectId": [
"597b029b93077c05214403be"
],
"tags": [],
"state": {
"mode": "lock"
},
"prompts": {
"confirm": [
"Are you from {location} location"
]
},
"samples": [
"test intent",
"test complete intent"
],
"slots": [],
"description": "",
"__v": 0,
"projectArrayLength": 1
}
],
"paging": {
"pageCount": 1,
"currentPage": 1,
"itemCount": 1,
"resultsCount": 1,
"hasMore": {
"hasPrevious": false,
"hasNext": false
}
}
}
Get a specific intent
To get a list of specific intents in the current server, use the following API call:
/api/voice/intent/:id
Example usage
curl -i http://[YOUR_ENDPOINT]/api/voice/intent/:id
GET Example
{}
Success Response
HTTP/1.1 200 OK
{
"_id": "5981b59e1c4266004c123b2b",
"modifiedAt": "2017-08-02T12:40:18.310Z",
"name": "test-b7a2b7c5-fe99-4650-a69a-a7b83ece239f",
"createdBy": "5971f9f8328af5c9637958b3",
"__v": 0,
"isDeleted": false,
"createdAt": "2017-08-02T11:21:02.994Z",
"projectId": [],
"tags": [],
"state": {
"mode": "lock"
},
"prompts": {
"confirm": [
"Are you from {location} location"
]
},
"samples": [
"test intent",
"test complete intent"
],
"slots": [
{
"name": "location",
"_id": "5981c832155cc0505aecf8b9",
"prompts": {
"elicit": [
"where are you from..?"
],
"confirm": [
"Did I hear {location}"
]
},
"samples": [
"Im from {location} ",
"My location is {location}"
]
}
],
"description": ""
}
POST
Creates a resource to the remote server.
To create an intent in the intent library, use the following API call:
/api/voice/intent?projectId=595b334f6b68b2f8042285a6
Example usage
curl -i http://[YOUR_ENDPOINT]/api/voice/intent
POST Example
{
"name": "test-b7a2b7c5-fe99-4650-a69a-a7b83ece239f",
"slots": [
{
"name": "location",
"samples": [
"Im from {location} ",
"My location is {location}"
],
"prompts": {
"confirm": [
"Did I hear {location}"
],
"elicit": "where are you from?"
}
}
],
"samples": [
"test intent",
"test complete intent"
],
"prompts": {
"confirm": [
"Are you from {location} location"
]
}
}
Success Example
HTTP/1.1 201 OK
{
"__v": 0,
"modifiedAt": "2017-08-02T11:21:02.994Z",
"name": "testb7a2b7c5fe994650a69aa7b83ece239f",
"createdBy": "5971f9f8328af5c9637958b3",
"_id": "5981b59e1c4266004c123b2b",
"isDeleted": false,
"createdAt": "2017-08-02T11:21:02.994Z",
"projectId": [],
"tags": [],
"state": {
"mode": "lock"
},
"prompts": {
"confirm": [
"Are you from {location} location"
]
},
"samples": [
"test intent",
"test complete intent"
],
"slots": [
{
"name": "location",
"_id": "5981b59e1c4266004c123b2c",
"prompts": {
"elicit": [
"where are you from?"
],
"confirm": [
"Did I hear {location}"
]
},
"samples": [
"Im from {location} ",
"My location is {location}"
]
}
],
"description": ""
}
PUT
Updates a resource in the remote server.
To edit an intent that is already created, use the following API call:
/api/voice/intent/:id?projectId=595b334f6b68b2f8042285a6
Example usage
curl -i http://[YOUR_ENDPOINT]/api/voice/intent/:id?projectId=595b334f6b68b2f8042285a6
PUT Example
{
"name": "test-b7a2b7c5-fe99-4650-a69a-a7b83ece239f",
"slots": [
{
"name": "location",
"samples": [
"Im from {location} ",
"My location is {location}"
],
"prompts": {
"confirm": [
"Did I hear {location}"
],
"elicit": "where are you from..?"
}
}
],
"samples": [
"test intent",
"test complete intent"
],
"prompts": {
"confirm": [
"Are you from {location} location"
]
}
}
Success Example
HTTP/1.1 200 OK
{
"_id": "5981b59e1c4266004c123b2b",
"modifiedAt": "2017-08-02T12:40:18.310Z",
"name": "test-b7a2b7c5-fe99-4650-a69a-a7b83ece239f",
"createdBy": "5971f9f8328af5c9637958b3",
"__v": 0,
"isDeleted": false,
"createdAt": "2017-08-02T11:21:02.994Z",
"projectId": [],
"tags": [],
"state": {
"mode": "lock"
},
"prompts": {
"confirm": [
"Are you from {location} location"
]
},
"samples": [
"test intent",
"test complete intent"
],
"slots": [
{
"name": "location",
"_id": "5981c832155cc0505aecf8b9",
"prompts": {
"elicit": [
"where are you from..?"
],
"confirm": [
"Did I hear {location}"
]
},
"samples": [
"Im from {location} ",
"My location is {location}"
]
}
],
"description": ""
}
DELETE
Deletes a resource in the remote server.
To delete an intent from the intent library, use the following API call:
/api/voice/intent/:id
Example usage
curl -i http://[YOUR_ENDPOINT]/api/voice/intent/:id
DELETE Example
{}
Success Example
HTTP/1.1 204 OK
{
}
Using Postman to access the REST APIs
The Postman is a great tool when trying to dissect RESTful APIs made by others or test the ones that you have made.
See https://www.youtube.com/watch?v=K3s0iT6rWe0 for a video that shows how to get started with Postman.
See also https://<sandbox-domain>:<portno>/apidoc, which shows the complete REST API documentation on the sandbox.
Adding Collections to Postman
It can be tiresome to test all the Orbita APIs by copying each API to Postman. To minimize the effort and the time consumed, we have provided a JSON to add a collection of all the APIs to Postman so that the admins can navigate to the required API and test it quickly. The two ways of importing JSON to Postman are described below.
Setting up an Environment in Postman
Copy the JSON code from the link http://<sandboxdomain>:<portno>/apidoc/postman/Environment.json and paste it in a separate file.
Select the cogwheel button on the top right corner of the application to manage environment settings.
Click “Import” from the dialog box.
Select the file. The environment file is loaded to the postman.
Click the file name to edit the environment settings and update your domain and token and click on “Update”.
How to get Token
Login to postman
Set the method to “POST” and use the URL https://<domain-name>:<portno>/api/login.
Use the below code in the body of the request and click “Send”. Please change the login credentials as per the instance/domain.
{ "username":"example@orbita.com", "password":"Password@123" }
You will receive a token in the response.
Select the Environment that you created from the Environment dropdown on the top right corner of the page.
Import using URL
Open Postman and Select the Import option.
Copy the link http://<sandbox-domain>:<portno>/apidoc/postman/ItemCollection.json and paste it in the “Import From Link” tab in the import dialog box and click “Import”.
Import Raw Text
Open Postman and Select the Import option.
Copy the JSON content in the link http://<sandbox-domain>:<portno>/apidoc/postman/ItemCollection.json and paste it in “Paste Raw Text” tab in the import dialog box and click “Import”.
