1. Help Center Home
  2. API
  3. Using the API
  4. API Framework & Technical Overview

API Framework & Technical Overview

Overview

This article provides a technical overview of the CIMcloud API Framework with examples.  This article is intended to be a technical introduction to the API. It is written for people with software development / programming skills.

Detailed Demo & Explanation Video

This is a detailed walkthrough of the CIMcloud API using Postman (a free API testing tool).  It demonstrates the API while providing lots of additional context and details.  We recommend watching this first, then reading/referencing the article.

Topics Covered

The following outlines the topics covered in this article:

  • A Few Technical Basics
  • Terminology
  • Authentication
    • Finding Your Authentication Credentials
    • Authentication Requests
  • API Health Checks
    • Canary
    • Healthcheck
  • GET Requests
  • POST Requests

This article complements the specific API end-point / resource documentation (that gets into granular field-level details) that is located in the API section of your CIMcloud Worker Portal.

Note: To access the API, 1) you have to purchase the API software bundle, and 2) your worker login has to have the API rights assigned to it (so you can see API links).

You can see a few screenshots of this API documents located in the Worker Portal in the CIMcloud API Introduction article.

The following additional articles can provide additional context when planning a project that requires the CIMcloud API.

  • CIMcloud API Introduction
    • This is a higher level (and less technical) overview of the CIMcloud API.
    • This article is good place to start (before you get into the technical detail presented below)
  •  The Integration Reference Guide (Using the CIMcloud API)
    • This is an overall reference guide for anyone considering an integration project that uses the CIMcloud API.
    • It includes lots of foundation best practices for forming and team, assigning roles, and using example tools / document templates to plan the work and manage the project.

A Few Technical Basics

This section covers a few technical basics related to the CIMcloud API.

  • Authentication is needed to make any requests to the API, excluding the canary endpoint, which allows anonymous users to ping for availability
  • Body of all requests are in a JSON format
  • On POSTs, either the primary key or user key can be used to identify a record to update.  If both are provided, the primary key wins.
  • Limitations
    • Default Client Rate Limit value is two calls per second and a hundred calls per fifteen minutes.
    • All POSTs and PUTs are limited to ten records per import; however, if the number of records on a POST or PUT exceed ten, then they will be added to an asynchronous queue to be processed.
    • All GETS return a max of fifty records per response, pagination is supported to retrieve more results, as well as search strings to filter results.
  • The API queue can make intelligent decisions if the detail records are added before the reference to a header record exist (i.e. if a request to import order detail lines is made before the order header exists, the queue will attempt to reimport the detail lines after the header has been created).

Note: Replace the {sitename} with your website’s sitename identifier in the below endpoints.  You can view your sitename once logged into Extranet.

Terminology

App Authorizations: Contains the credentials to connect to the API, IP address filtering, and the API Resources that are mapped to an App Authorization

  • For example, you could create an authorization to only allow GETs, and another authorization that allows GETs and POSTs, for segmented calls to the same data store with user permissions based off the Authorization credentials.

API Resources: The data that is accessible via HTTP Methods.  API Resources have four types associated to them:

  • Standard
    • Allows GETs, POSTs, PUTs, and DELETEs on a single database table
    • Searchstrings are allowed
  • Complex
    • Only GETs are available for this type
    • Allows a custom query to return data from multiple database tables
    • (Optional) Allows you to manipulate data after an API call
      • For example, if you wanted to only retrieve orders that have not been retrieved previously, you could setup a Complex API Resource to GET the orders and mark the orders as retrieved, avoiding duplicate results on the following GET requests.
    • Searchstrings are allowed on the specified table
  • Special
    • Calls a function when the resource is called.
    • Searchstrings are not allowed

API Resource – Tag: Groups resources together to dynamically generate exposed API endpoints per authorization.

API Resource – HTTP Path: The unique address of an endpoint for an API Call.

Authentication

Finding Your Authentication Credentials

Head to the backend of your website to obtain the credentials

  1. With Classic Sites (webdriver)
    1. Login to webdriver
    2. Click on “API Manager” -> “App Authorizations” -> “Manage”
    3. Click “View” under the actions column for the resource you’d like the credentials for
    4. Your credentials are under the “Authorization Information” section and are passed to the Authentication endpoint below to retrieve your token
      1. Please Note: Your Authorization Password is hashed and can only be reset (i.e. we cannot retrieve the current authorization password since it is not stored in a plaintext format).  You should make note of the Authorization Password used on creation, or reset, to minimize disruptions.
  2. New CIMCloud platform (worker portal)
    1. Login to the Worker Portal
    2. Search for App Authorizations and click on the menu link
    3. Click “View” under the actions column for the resource you’d like the credentials for
    4. Your credentials are under the “Authorization Information” section and are passed to the Authentication endpoint below to retrieve your token

Authentication Requests

Description: Creates a token that expires after 7 days from creation.  This is an authentication type of “Bearer Token” and must be passed with each corresponding HTTP request (excluding the canary endpoint).  There is no limit on the number of generated bearer tokens (i.e. you can authenticate and generate a bearer token as often as you’d like).

Endpoint: https://api.cimcloud.com/{sitename}/authenticate

Body (set the values obtained from the Finding Your Authentication Credentials section above):

{
"AuthKey": "xxxxxxxxxxx",
"AuthUserName": "xxxxxxxxxxx",
"AuthPassword": "xxxxxxxxxxx"
}

Successful Response:

{
"expiration": "2022-01-01T01:00:00Z",
"token": "xxxxxxxxxxx"
}

API Health Checks

The CIMcloud API supports the following two health checks.  These are both GET requests.

Canary

Description: No authentication token needed, allows you to check the status of the API layer to determine if the API layer is down or running.

Endpoint: https://api.cimcloud.com/{sitename}/healthcheck/canary

Healthcheck

Description: Requires the Authentication Bearer Token to be passed.  Similar to the canary, but allows you to verify the token is still available.

Endpoint: https://api.cimcloud.com/{sitename}/healthcheck

GET Requests

Overview

GET requests allow you to get data from the CIMcloud API / platform.

Pagination

The default records returned on a GET request is 50 results.  You can use pagination to cycle through results with the following format:

Endpoint: https://api.cimcloud.com/{sitename}/{resource}/{searchstring}/{page_number}

  • Notes:
    • {page_number} starts at 1, where an empty or 0 value is treated the first 50 records
    • {searchstring} is optional (please see the searchstring section below for more information on this format)

Examples:

  • https://api.cimcloud.com/{sitename}/accounts/1
  • https://api.cimcloud.com/{sitename}/accounts/searchlike~nm~bob/2
  • https://api.cimcloud.com/{sitename}/accounts/3
  • etc

API Filtering (Using Searchstrings)

Searchstrings allow you to filter the returned results in a GET request.  This section introduces the allowable searchstrings to append to an endpoint.

The example format is:

  • {endpoint}/{searchstring}
  • Example on the Products endpoint:
    • https://api.cimcloud.com/{sitename}/product/searchexact~sku~blueshirt

Complete details:

Use this article to find the allowable searchstrings that can be appended to an API endpoint – https://help.cimcloud.com/help-center/api-get-filtering-using-searchstrings/.

Example: Get All Accounts

Description: Endpoint to retrieve all accounts.

Endpoint: https://api.cimcloud.com/{sitename}/account/

Example: Get All Customers

Description: Endpoint to retrieve all customers.

Endpoint: https://api.cimcloud.com/{sitename}/customer/

Example: Get All Products

Description: Endpoint to retrieve all products.

Endpoint: https://api.cimcloud.com/{sitename}/product/

Example: Get Online Orders

Description: A complex resource type to retrieve orders placed on the site where [orders].exported = ‘0’; setting the [orders].exported flag to ‘1’ after a GET request.  Purpose is to GET new orders without risk of duplication.

Endpoint: https://api.cimcloud.com/{sitename}/OnlineOrders

Notes

  • Although a GET request is made, the complex API resource type automatically filters on the [orders] table where the exported flag is set to 0
  • This HTTP method uses a custom GET query to pull the order details from multiple tables including:
    • Order Header [orders]
    • Order Details [order_detail]
    • Product Information [product]
    • Account Information [accounts]
    • Customer Information [customers]
    • Credit Card Information (PCI Compliant) [credit_card_nicknames]
    • Shipping Address [shipping_addresses]
    • Payment [payments]
  • Once a GET request is made to the OnlineOrders endpoint, the [orders].exported flag is set to 1
  • To retrieve the same orders a second time, a POST request should be made to an Orders resource with a “standard” type passing the exported flag as 0

Successful Response:

[
    {
    "c_ordnum": 115860,
    "o_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Header_WS_ID": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "CouponData_Amount": 0.0000,
    "CouponData_UserCode": "",
    "CouponData_ItemCode": null,
    "GiftCard_DepositAmt": 0.0000,
    "GiftCard_UserCode": "",
    "GiftCard_ItemCode": "/GIFT",
    "OrderComment_Text": "TEST ORDER",
    "OrderComment_ItemCode": "/C",
    "ExtraDetail_1_Comment": "",
    "ExtraDetail_1_ItemCode": "/C",
    "ExtraDetail_1_ItemType": "4",
    "ExtraDetail_1_PostExtraLine": "0",
    "Header_CommentText": null,
    "TaxData_TaxSchedule": "SC PIC",
    "Header_ERPOrderNumber": null,
    "Header_SalesOrderNo": null,
    "header_CancelReasonCode": "",
    "header_OrderStatus": null,
    "header_PrintPickingSheets": null,
    "header_PrintSalesOrders": null,
    "header_WarehouseCode": null,
    "Header_SalespersonNo": "Z",
    "Header_DivisionNo": "00",
    "Header_ConfirmTo": " ",
    "Header_FaxNo": "864-123-0000",
    "Header_CustomerNo": "WSP100",
    "header_FreightAmt": 0.0000,
    "Header_CustomerPONo": "TEST ORDER",
    "Header_ShipVia": "CPU",
    "Header_OrderDate": "2010-00-00T17:07:39.817",
    "Header_BillToName": "Website Pipeline",
    "Header_BillToAddress1": "123 Main Street",
    "Header_BillToAddress2": "",
    "Header_BillToAddress3": "",
    "Header_BillToCity": "Greenville",
    "Header_BillToState": "SC",
    "Header_BillToZipCode": "29607",
    "Header_BillToCountryCode": "USA",
    "Header_BillToCustomerNo": "WSP100",
    "Header_BillToDivisionNo": "00",
    "Header_ShipToName": "",
    "Header_ShipToAddress1": "123 Main Street",
    "Header_ShipToAddress2": "Suite 123",
    "Header_ShipToAddress3": "",
    "Header_ShipToCity": "Greenville",
    "Header_ShipToState": "SC",
    "Header_ShipToZipCode": "29607",
    "Header_ShipToCountryCode": "USA",
    "Header_TermsCode": "30",
    "Header_EmailAddress": "joe@gmail.com",
    "Header_ShipExpireDate": "2024-01-04T21:15:22.55",
    "Header_DiscountRate": 0.00,
    "Customer_CustomerNo": "WSP100",
    "Customer_DivisionNo": "00",
    "Customer_SalespersonNo": "Z",
    "Customer_TaxSchedule": "SC",
    "Customer_TermsCode": "30",
    "Customer_UpdateCustomerMaster": "false",
    "Customer_FaxNo": "864-123-0000",
    "Customer_CustomerName": "CimCloud",
    "Customer_AddressLine1": "123 Main Street",
    "Customer_AddressLine2": "",
    "Customer_AddressLine3": null,
    "Customer_City": "Greenville",
    "Customer_State": "SC",
    "Customer_ZipCode": "29607",
    "Customer_CountryCode": "USA",
    "Customer_CreditHold": "N",
    "Customer_CustomerType": "OT",
    "Customer_EmailAddress": "joe@gmail.com",
    "Customer_ShipMethod": null,
    "Customer_TaxExemptNo": null,
    "Customer_TelephoneExt": "105",
    "Customer_TelephoneNo": "864-123-0000",
    "Customer_URLAddress": "",
    "Customer_PriceLevel": "Z",
    "ShipTo_ShipToCode": "W007",
    "ShipTo_LookupShipToAddressFromShipToCode": "false",
    "ShipTo_UpdateShipToMaster": "true",
    "ShipTo_ShipToName": "",
    "ShipTo_ShipToAddress1": "123 Main Street",
    "ShipTo_ShipToAddress2": "Suite 123",
    "ShipTo_ShipToAddress3": "",
    "ShipTo_ShipToCity": "Greenville",
    "ShipTo_ShipToState": "SC",
    "ShipTo_ShipToZipCode": "29607",
    "ShipTo_ShipToCountryCode": "USA",
    "ShipTo_TaxSchedule": "SC PIC",
    "ShipTo_TelephoneNo": "864-123-1000",
    "ShipTo_EmailAddress": "real.customer@gmail.com",
    "ShipTo_SalespersonDivisionNo": "00",
    "ShipTo_SalesPersonNo": "Z",
    "ShipTo_WarehouseCode": null,
    "CreditCard_Gateway": null,
    "CreditCard_AVSAddress": null,
    "CreditCard_AVSAddress2": null,
    "CreditCard_AVSCity": null,
    "CreditCard_AVSState": null,
    "CreditCard_AVSZipCode": null,
    "CreditCard_AVSCountry": null,
    "CreditCard_CardholderName": null,
    "CreditCard_ExpirationDateMonth": "",
    "CreditCard_ExpirationDateYear": "",
    "CreditCard_VaultId": null,
    "CreditCard_First2": null,
    "CreditCard_Last4": null,
    "CreditCard_CardID": null,
    "Payment_DepositAmt": 0.0000,
    "Payment_CreditCardAuthorizationNo": null,
    "Payment_PaymentType": "",
    "Payment_CreditCardPayment": "0",
    "Payment_CreditCardTransactionID": null,
    "Payment_PaymentResponseXML": "<xml></xml>",
    "Payment_PaymentResponseAuthorizeCIM": "",
    "Payment_TransactionDate": "",
    "Payment_TransactionTime": "",
    "Payment_PostDepositAmt": null,
    "Payment_PaymentTypeCategory": "P",
    "Payment_OtherPaymentTypeRefNo": null,
    "Payment_APISecret": null,
    "details": [
        {
            "QuantityOrdered": 1.0000,
            "ItemCode": "SHIRT001",
            "UnitPrice": 34.9900,
            "UnitOfMeasure": "",
            "Comment": "",
            "WarehouseCode": null
        }
    ]
}
]

GET: Searchstrings on Complex Resource Types

Complex resource types allow highly customizable queries to manipulate records.  To allow searchstrings when the Resource Type is set to “Complex”, any of the following syntax should be included in your GET query:

  • {{searchstring(where)}}
    • Appends a searchstring to your custom GET query (without the WHERE clause defined)
    • Example Query: Returns all products where you can append filters within your API calls
      • select * from products {{searchstring(where)}}
  • {{searchstring(and)}}
    • Uses the WHERE clause in your custom GET query and appends optional searchstrings in your API calls
    • Example Query: Returns only enabled products, allowing additiional filtering with an AND searchstring
      • select * from products where isnull(status, ‘1’) = ‘1’ {{searchstring(and)}}
  • {{searchstring(or)}}
    • Allows you to override the WHERE clause in your custom GET query.
    • Example Query: Allows you to override the filter on the query to GET enabled products with an OR searchstring in your API Call
      • select * from products where isnull(status, ‘1’) = ‘1’ {{searchstring(or)}

POST Requests

Overview

POST requests allow you to add or edit data in the CIMcloud platform via the API

  • If a data record sent via a POST already exists, it will update it.
  • If a data record sent via a POST does not exists, it will add a new record.

PUT request allow you to update existing data records in the CIMcloud platform via the API (if the data record PUT does not exist, a record will not be added).

Example: Create an Account

HTTP Request Type: POST

Endpoint: https://api.cimcloud.com/{sitename}/account/

Example Body:

{ 
"ref_id": "00-TEST012", 
"nm": "Test Account", 
"status": "1"
}

Successful Response:

{

"action": "DataImported",

"success": true,

"importedRecords": 1,

"updatedRecords": 0,

"recordCountInRequest": 1,

"message": null

}

 

 

 

 

 

 

Was this article helpful

Related Articles

Subscribe to receive email updates of what's new in the CIMcloud Help Center.