The purpose of this guide is to provide background and instruction for utilizing Sharpen’s API Gateway (not legacy API).

The API Gateway is Sharpen’s external API interface to microservice-based functions. If you’re dealing with an API that contains api.sharpencx.com or api.fathomvoice.com, this is not the api gateway. Instead the api gateway will contain api.sharpen.cx in its URL.

Whereas the legacy api leveraged cKey1 and cKey2 on behalf of the organization as a whole, the api gateway leverages user-based api keys and secrets based on a unique JWT (Json Web Token). The api gateway leverages POST, GET, PUT, DELETE, etc. methods instead of just POST from the legacy API.

Table of Contents

Where to access

The API gateway api calls and documentation can be accessed one of two ways; the API Gateway web page, or the preconfigured collection from the Postman collection below. The preconfigured collection contains configurations and examples for Authorization and common SharpenDB2 requests.

API Gateway documentation: Sharpen Public API

Postman download: Postman download

While there are many REST API tools available, we recommend Postman. The export below is in Postman json export v2.1

API Gateway Postman export:

Setting up authorization

In order to send API calls using the API gateway, a system of BearerAuth, apiKey, and apiSecret are used. To start off, you need to gather your Json Web Token

Gathering your JWT(Json Web Token)

Create Authorization API call method

Using Postman, import the API collection above
Once imported, navigate to the ‘Create New Authentication’ API call under the ‘Authorization setup' folder
Identify the ‘Authorization’ tab once selecting the api from the folder list
Choose ‘Basic Auth’ from the drop down
Enter the credentials of the Sharpen account corresponding with the account you’re interfacing with
Click ‘Send’
Response should look like

Login to App method (alternative to the method above)

Process

Identify Sharpen account you will be executing the API call against
Login to that account via app.sharpencx.com or app.iz1.sharpen.cx
After logging in, right-click in an empty space on the page, and choose ‘Inspect’
Navigate to the ‘Application’ tab
Under ‘Storage’ on the left side, expand ‘Session Storage’
Identify ‘apiAuthToken’
The string in the ‘Value’ field is your token

Gathering apiKey and apiSecret

Navigate to the ‘Create API Key’ api call under the ‘Authorization Setup’ folder within the imported Postman collection.
Click the ‘Authorization’ tab and choose ‘Bearer Token’.
Insert the token gathered in step 7 of “Gathering your JWT” here
Navigate to the ‘Body’ tab
If you want an expiration on the token, update the date/time to the proper expiration time. If you do not want an expiration, modify the body to look like this.
Click ‘Send’
The return should look like this

The language of the response needs translation to what is expected later in the flow

clientId = api-key
clientSecret = api-secret

Executing API call

The examples below are some of many types of API calls which can be run. These show how to create a table and query SharpenDB from the API Gateway. Please refer to the core API Gateway reference to see all available API calls.

Create Table

Identify the ‘Create Table’ request under the ‘SharpenDB2’ folder in the Postman collection
Under the ‘Authorization’ tab, set the ‘Type’ to “No Auth”
Under the ‘Headers’ tab add the following keys (x-api-key and x-api-secret)
Enter the values in correspondence with what was retrieved in the ‘Gathering apiKey and apiSecret’ section of this document
Under the ‘Body’ tab enter your query in JSON format
Click ‘Send’
The request and response should look something like this…

Query

Identify the ‘SharpenDB2 Select’ request under the ‘SharpenDB2’ folder in the Postman collection
Under the ‘Authorization’ tab, set the ‘Type’ to “No Auth”
Under the ‘Headers’ tab add the following keys (x-api-key and x-api-secret)
Enter the values in correspondence with what was retrieved in the ‘Gathering apiKey and apiSecret’ section of this document
Under the ‘Body’ tab enter your query in JSON format
Click ‘Send’
The request and response should look something like this…

QUERY Examples

The examples below show how to convert common mySQL queries into json bodies for the api requests above.

JSON Examples

SELECT

SELECT `file` FROM SoundFiles WHERE `inboundNumber` = '5551234567'
{
  "type": "select",
  "fields": [ "file" ],
  "condition": [
    {
      "inboundNumber": {"$eq": "5551234567"}
    }
  ]
}

SELECT with JOIN

SELECT * FROM PhoneNumbers JOIN Clients ON PhoneNumbers.number = Clients.number;
{
  "type": "select",
  "join": {
    "Clients": {
      "on": {"PhoneNumbers.number": "Clients.number"}
    }
  }
}

INSERT

INSERT INTO Clients (name, age, number) VALUES ("John", 24, "5551234567");
{
  "type": "insert",
  "values": [
    {
      "name": "John",
      "age": 24,
      "number": "5551234567"
    }
  ]
}

UPDATE

UPDATE Clients SET age = 25, number = "5552345678" WHERE name = 'John';
{
  "type": "update",
  "condition": {
    "name": "John"
  },
  "modifier": {
    "age": "25",
    "number": "5552345678"
  }
}

DELETE

DELETE FROM Clients WHERE number = "5551234567";
{
  "type": "remove",
  "condition": {
    "number": "5551234567"
  }
}

CX Examples

Code Example:

The following example of code will return the entire contents of the table JSDLookup. Please note that the table name is listed in the CURLOPT_URL as part of the API call, and needs to be updated to the respective table on your account.

1<?
2// Set API key/secret pair
3$apiKey = 'aaaa';
4$apiSecret = 'bbbb';
5
6// Define the API URL with the desired table name.
7$tableName = 'JSDLookup';
8$url = "https://api.sharpen.cx/v1/sharpendb/tables/" . $tableName . "/query";
9
10// Define the query
11$q = '{
12    "type": "select",
13    "distinct" : false,
14    "limit": 100,
15    "offset": 0,
16    "count": false
17}';
18
19// Define the api key/secret pair and the content type as json.
20$headers = array(
21    "content-type: application/json",
22    "x-api-key: " . $apiKey,
23    "x-api-secret: " . $apiSecret
24);
25$curl = curl_init();
26curl_setopt_array($curl, array(
27  CURLOPT_URL => $url,
28  CURLOPT_RETURNTRANSFER => true,
29  CURLOPT_ENCODING => "",
30  CURLOPT_MAXREDIRS => 10,
31  CURLOPT_TIMEOUT => 5,
32  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
33  CURLOPT_CUSTOMREQUEST => "POST",
34  CURLOPT_POSTFIELDS => $q,
35  CURLOPT_HTTPHEADER => $headers,
36));
37$response = curl_exec($curl);
38curl_close($curl);
39echo $response;

Query Structure:

The following will result in a SELECT * FROM 'table' query:

1{
2	'type' => 'select',
3    'distinct' => false,
4    'limit' => 100,
5    'offset' => 0,
6    'count' => false
7}

Example Response:

This is an example of a full table of data returned via the Query API:

1{
2  "query": "select * from `JSDLookup` limit 100 offset 0;",
3  "results": [
4    {
5      "LookupID": 1,
6      "email": "billybob@bob.com",
7      "JSDaccountID": "supersecretID",
8      "username": "1234con1234"
9    },
10    {
11      "LookupID": 2,
12      "email": "janeydoey@jane.com",
13      "JSDaccountID": "evenmoresecretID",
14      "username": "4567con1234"
15    },
16    ...
17  ]
18}

API Gateway Initial Setup