The purpose of this guide is to provide instruction for utilizing Sharpen’s API Gateway.

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

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

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:

Open

Importing Collection into Postman

1. Download Postman here

2. Install Postman

3. Using Postman, import the API collection above

   Open

   

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

      Open

      

4. Click “Save” at the top right.

Gathering your JWT(Json Web Token)

Create Authorization API call method

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

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 make sure ‘Bearer Token’ is chosen.

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

6. Click ‘Send’

7. The return should look like this

Executing API calls

The examples below are some of many API calls which can be run. 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 API Gateway docs to see all available API calls.

Create Table

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

2. Under the ‘Headers’ tab update the x-api-key and x-api-secret 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

   [ { "name": "TableName" } ]

4. Click ‘Send’

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

Create Column

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

2. Under the ‘Headers’ tab update the x-api-key and x-api-secret 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

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

4. Click ‘Send’

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

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

2. Under the ‘Headers’ tab update the x-api-key and x-api-secret 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

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

4. Click ‘Send’

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