The CIMcloud API Introduction

Overview

This article provides an overview of the CIMcloud API.  It covers the following topics:

• “API” Defined (a Few Concepts)
  • Business Logic (in the API)
  • The “Sync Tool”
• The CIMcloud API Introduction
• The CIMcloud API Framework Documentation
  • Screenshots (of specific API docs found in your Worker Portal)

Available As an Optional Software Bundle

The CIMcloud API is sold as an optional software add-on bundle, called the “API System with Standard GETs / POSTs and 2 App Authorizations [API2]”.  You must be on the CIMcloud Standard Edition (or higher) to purchase this bundle.

Part of a Series of Articles

The article you are currently reading is part of a series of articles that are all organized and summarized in this Integration Reference Guide (Using the CIMcloud API).

Audience (for This Article)

The intended audience for this article is CIMcloud customers (and their contractors / partners) that are considering building and/or managing / supporting an integration between CIMcloud and any other software system.

“API” Defined (a Few Concepts)

API is an industry-standard acronym that stands for “Application Programming Interface”.  That’s just a fancy was of saying it is a standard way for separate software systems to securely talk to each other (including passing data back and forth).  The API is the interface, that is optionally build into software (most modern / commercial software applications have an API), that allows other software applications to “talk” to it.  They “talk” to it by programmatically calling a website address (that is built into the API and set to receive calls – this is called an endpoint) and

1. Asking it for data – this is referred to as a GET
2. Sending data to add or update – this is referred to as a POST or PUT
3. Sending data to delete – this is referred to as a DELETE

Business Logic (in the API)

Most software applications with an API also access business logic that performs additional actions 1) before responding to the GET with the data asked for, or 2) after receiving the data sent through a POST or PUT.

The “Sync Tool”

For complex integrations (between two software systems), some software mechanism is actually moving the data between the two systems.  We are generically calling this a “Sync Tool”.  When moving data, the sync tool is calling an API (or something else that allows it to send / receive data) on the source software system, translating it into a format that is understood by the destination software system, calling the destination API (or equivalent) and sending the data, and then logging the results (and possibly taking further actions if the results were not successfully received by the destination software system).

This API article on Wikipedia has lots of details (if you care to brush up).

The CIMcloud API Introduction

The CIMcloud API is an optional software bundle that can be purchased and used to integrate other software applications with CIMcloud.  It is one part of a larger set of software developer tools that CIMcloud has available to customize, extend, and integrate the CIMcloud platform.

The API requires technical / software developer skills to use.

The API includes the following capabilities:

• Create & manage App Authorizations for each software application that will use the API.
  • This includes establishing security credentials for the “App” (the software tool talking to the API) to access the API, determining which “Resources” (the data tables / entities) the API provides access to, and optionally restricting the IP address that can hit the API.
• Ability to GET data (“Resources”) from CIMcloud including accounts, contacts, addresses, products, inventory levels, product pricing, online orders, online invoice payments, order history (header and lines), shipments, invoice history (header and lines), payments, credits, etc.
  • The API allows access to a single record, all records, or a sub-set of records based on a filter you pass (think of this as a SQL “where”… we call it a “search string”).
• Ability to POST, PUT, and/or DELETE data (“Resources”) from CIMcloud including the same data entities listed above.
  • The API allows you to post a single record or small batch of records (up to 10) synchronously or a large batch of records (over 10) asynchronously.

The CIMcloud API Framework Documentation

This is the commercial & technical documentation that your integration project team will need to plan and complete the integration project.  This includes the following additional articles:

• The CIMcloud API Introduction
  • This is the article you are currently reading.
  • It provides a commercial overview of the “API System with Standard GETs / POSTs and 2 App Authorizations [API2]” add-on software bundle.
• API Framework/Technical Overview (With Example POSTs / GETs)
  • This is the technical overview of the API, how to call it, what it returns, etc.
  • It generally covers terminology, the Canary (health check) endpoint calls, the Authentication endpoint calls, GET (including using searchstrings to filter records returned) calls, and POST calls.
  • Note: This specific endpoints, including field definitions, are located in your CIMcloud Worker Portal and are introduced in the “Specific Documentation” section below.
• API GET Filtering (Using Searchstrings)
  • This is a technical deep dive on the advanced filtering that can be leveraged to filter the records returned when making GET calls to the API.
• Specific Documentation on Every API Endpoint (Including Field-Level Details)
  • The CIMcloud Worker Portal’s API section (a link on the Manage App Authorizations page) automatically builds and displays specific & detailed documentation for every Resource (and End Point) that is available to call via the API.  It includes field-level definitions.
  • Log into your CIMcloud Worker Portal (or Web Driver on classic sites) to access the documentation.
  • The section below includes screenshots of this documentation (for quick reference).

Screenshots (of specific API docs found in your Worker Portal)

The following are screenshots of the specific API documents inside your Worker Portal.

Note: You must purchase the API Bundle to get / see these interfaces.

Screenshot #1: Available Resources

The listing of all Resources (endpoints) this App Authorization can access (once authenticated).

Screenshot #2: Field-Level Details on Any Resource

Drilling into a specific Resource (endpoint) to see the field-level payload.

Screenshot #3: Data Schemas With Field Descriptions

A listing of the specific data schema, with drill down to see field-level descriptions.