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 within the SharpenCare Postman workspace.

API Gateway documentation: Sharpen Public API

API Gateway Postman export: Postman download

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

1. Using Postman, import the API collection above

2. Once imported, navigate to the “Create New Authentication” API call

3. Identify the ‘Authorization’ tab

4. Choose ‘Basic Auth’ from the drop down

5. Enter the credentials of the Sharpen account corresponding with the account you’re interfacing with

6. Click ‘Send’

7. Response should look like

   

Login to App method (alternative to the method above)

Gathering apiKey and apiSecret

1. Navigate to the Create API Key api call within the imported Postman collection.

2. Click the ‘Authorization’ tab and choose ‘Bearer Token’.

   

3. Insert the token gathered in step 7 of “Gathering your JWT” here

4. Navigate to the ‘Body’ tab

5. 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.

   

6. Click ‘Send’

7. The return should look like this

   

Executing API call

The example below is one of many types of API calls which can be run. It shows how to query SharpenDB from the API Gateway. Please refer to the core API Gateway reference to see all available API calls.

Create Table

1. Identify the ‘Create Table’ request in the Postman collection

2. Under the ‘Authorization’ tab, set the ‘Type’ to “No Auth”

3. Under the ‘Headers’ tab add the following keys (x-api-key and x-api-secret)

   

4. Enter the values in correspondence with what was retrieved in the ‘Gathering apiKey and apiSecret’ section of this document

5. Under the ‘Body’ tab enter your query in JSON format

6. Click ‘Send’

7. The request and response should look something like this…

   

Query

1. Identify the ‘SharpenDB2 Select’ request in the Postman collection

2. Under the ‘Authorization’ tab, set the ‘Type’ to “No Auth”

3. Under the ‘Headers’ tab add the following keys (x-api-key and x-api-secret)

   

4. Enter the values in correspondence with what was retrieved in the ‘Gathering apiKey and apiSecret’ section of this document

5. Under the ‘Body’ tab enter your query in JSON format

6. Click ‘Send’

7. The request and response should look something like this…

   

Examples

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

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

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

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

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

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;

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

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}