...

...

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

Postman download: Postman download

...

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. 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 . To start off, you need to gather your Json Web Tokenin any subsequent API call.

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

1. Using Postman, import the API collection above

   Image Removed

2. Once imported, navigate Navigate to the ‘Create New Authentication’ API call under the ‘Authorization setup' folder

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

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 under the ‘Authorization Setup’ folder within the imported Postman collection.

2. Click the ‘Authorization’ tab and choose make sure ‘Bearer Token’ is chosen.

   

3. Insert the token gathered in step 7 6 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

...

calls

The examples below are some of many types of API calls which can be run. These 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 ‘SharpenDB2’ ‘SharpenDB2->Tables’ folder in the Postman collection

2. Under the ‘Authorization’ ‘Headers’ tab , set the ‘Type’ to “No Auth”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

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

   Code Block
   language json
   [ { "name": "TableName" } ]

4. Click ‘Send’

5. 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 add update the following keys ( x-api-key and x-api-secret)

   Image Removed

   Enter the values in correspondence with what was retrieved in the ‘Gathering apiKey and apiSecret’ section of this document values to match that of the values you retrieved in “Gathering apiKey and apiSecret” above.

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

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

4. Click ‘Send’

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

   Image AddedImage Removed

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 ‘SharpenDB2’ ‘SharpenDB2->Queries’ folder in the Postman collection

2. Under the ‘Authorization’ tab, set the ‘Type’ to “No Auth”Under the ‘Headers’ tab add update the following keys ( x-api-key and x-api-secret)

   Image Removed

   Enter the values in correspondence with what was retrieved in the ‘Gathering apiKey and apiSecret’ section of this document values to match that of the values you retrieved in “Gathering apiKey and apiSecret” above.

   Image Added

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

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

4. Click ‘Send’

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

   Image RemovedImage Added

Anchor
Examples Examples

QUERY Examples

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

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}

...