Versions Compared

Version Old Version 5 New Version Current
Changes made by

Mack Baczynski

Mack Baczynski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 or api.iz1.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

...

Table of Contents
minLevel1
maxLevel1
typeflat
separatorpipe

...

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.

Anchor
API_gateway_docs
API_gateway_docs

API Gateway documentation: IZ0 Sharpen Public API, IZ1 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:

View file
nameAPI Gateway Initial Setup.postman_collection.json

Importing Collection into Postman

  1. Download Postman here

  2. Install Postman

  3. Using Postman, import the API collection above

    Image Added

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. The steps below will guide you through obtaining the apiKey and apiSecret which will be necessary. Please keep in mind that the user you’re authenticating with will be the user executing the API calls. It is highly recommended you create an automation user within Sharpen which can persist through employee turnover.

Configure the {{base_url}}

Sharpen has two main isolation zones. Depending on which isolation zone you’re interfacing with, the api base url will be different. The Postman collection has a {{base_url}} variable which needs to be set to the appropriate environment before getting started. Once set, this base_url will be used in any subsequent API call.

Panel
bgColor#B3F5FF

By default, the base_url is set to https://api.iz1.sharpen.cx/v1. Please adjust this configuration if you’re using IZ0.

  1. Navigate to the ‘API Gateway Setup’ folder in Postman from your recently imported collection.

  2. Choose the ‘Variables’ tab.

  3. Check the box next to the appropriate "base_url" variable to correspond with the isolation zone in use.

    1. Only 1 may be checked.

    2. If you login to app.sharpencx.com, then use https://api.sharpen.cx/v1 as your base url.

    3. If you login to app.iz1.sharpen.cx, then use https://api.iz1.sharpen.cx/v1 as your base url.

      Image Added

  4. Click “Save” at the top right.

Gathering your JWT(Json Web Token)

Create Authorization API call method

...

Using Postman, import the API collection above

...

  1. Navigate to the ‘Create New Authentication’ API call under the ‘Authorization setup' folder

  2. Identify the ‘Authorization’ tab once selecting the api from the folder list

  3. Choose ‘Basic Auth’ from the drop down

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

  5. Click ‘Send’

  6. Response should look like

    Image Modified

Login to App method (alternative to the method above)

Expand
titleProcess

  1. Identify Sharpen account you will be executing the API call against

  2. Login to that account via app.sharpencx.com or app.iz1.sharpen.cx

  3. After logging in, right-click in an empty space on the page, and choose ‘Inspect’

  4. Navigate to the ‘Application’ tab

  5. Under ‘Storage’ on the left side, expand ‘Session Storage’

  6. Identify ‘apiAuthToken’

  7. The string in the ‘Value’ field is your token

Gathering apiKey and apiSecret

  1. Navigate to the ‘Create API Key’ api call under the ‘Authorization Setup’ folder within the imported Postman collection.

  2. Click the ‘Authorization’ tab and

...

  1. make sure ‘Bearer Token’ is chosen.

    Image Modified

  2. Insert the token gathered in step

...

  1. 6 of “Gathering your JWT” here

  2. Navigate to the ‘Body’ tab

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

...

  1. reflect.

...

  1. Image AddedImage Added

  2. Click ‘Send’

  3. The return should look like this

    Image Modified
info
Panel
bgColor
#DEEBFF

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

clientId = api-key
clientSecret = api-secret

Panel
panelIconId1f60e
panelIcon:sunglasses:
panelIconText😎
bgColor#C0B6F2

You’re now setup with the API Gateway

Executing API

...

calls

The example examples below is one are some of many types of API calls which can be run. It shows how to In particular, the examples below deal with the SharpenDB functionality within the API Gateway. They show how to create a table, column(s), and query SharpenDB from the API Gateway. Please refer to the core API Gateway referencedocs to see all available API calls.

Create Table

  1. Identify the ‘Create Table’ request under the

...

  1. ‘SharpenDB2->Tables’ folder in the Postman collection

  2. Under the

...

  1. ‘Headers’ tab

...

  1. update the x-api-key and x-api-secret values to match that of the values you retrieved in “Gathering apiKey and apiSecret” above.

    Image Added

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

    Code Block
    languagejson
    [
  {
    "name": "TableName"
  }
]

  3. Click ‘Send’

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

    Image Added

Create Column

  1. Identify the ‘SharpenDB2 Create Column’ request under the ‘SharpenDB2->Columns’ folder in the Postman collection.

  2. Under the ‘Headers’ tab

...

  1. update the

...

  1. x-api-key and x-api-secret

...

  1. values to match that of the values you retrieved in “Gathering apiKey and apiSecret” above.

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

    Code Block
    languagejson
    [
  {
    "field": "columnName",
    "type": "varchar(255)",
    "nullable": true,
    "default": "string"
  }
]

  3. Click ‘Send’

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

    Image Added

...

Query

The Query SharpenDB api allows for your standard SQL operations to be committed to a structured table. This includes SELECT, INSERT, UPDATE, and DELETE.

  1. Identify the ‘SharpenDB2 Select’ request under the

...

  1. ‘SharpenDB2->Queries’ folder in the Postman collection

  2. Under the

...

  1. ‘Headers’ tab

...

  1. update the

...

  1. x-api-key and x-api-secret

...

  1. values to match that of the values you retrieved in “Gathering apiKey and apiSecret” above.

    Image Added

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

    Code Block
    languagejson
    {
"type": "select",
  "condition": 
    {
      "columnName": {
        "$eq": "value"
      }
    }
}

  3. Click ‘Send’

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

...

  1. Image Added

Anchor
Examples
Examples
QUERY Examples

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

Expand
titleJSON Examples

SELECT

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

SELECT with JOIN

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

INSERT

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

UPDATE

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

DELETE

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

Expand
titleCX 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.

Code Block
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:

Code Block
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:

Code Block
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}

...