THE ANATOMY OF AN ELEMENT: A GUIDE TO CLOUD ELEMENTS' ENHANCED CONNECTORS

By Jackie Rebrovic in Enterprise Integration, SaaS Integration Posted Feb 5, 2018

It's clear that today's software companies need integration. Your customers expect your application to work with the other apps they use right out-of-the-box. They don’t want to figure it out on their own or worse, engage a third-party to enable integrations (and we don't think they should).

AoaE-lp-banner-01-1.png

With over 130 Elements in our catalog, we offer more pre-built integrations to the apps and services you need than anyone else. And our Elements go beyond simple connectors - with each Element you get advanced features designed to provide a unified experience for your developers. At Cloud Elements we believe software providers should shift the burden of integrating away from users, by insulating you from the complexities of underlying APIs.

We have built each Element with a range of advanced features and services like standardized auth, eventing, paging, error handling, bulk support, custom data discovery. Let's dive into the anatomy of an Element. 

anatomy-overview-01.pngNORMALIZED APIs 
Normalized APIs map resources from a collection of endpoints into a standardized set of APIs using a consistent RESTful API with a JSON payload regardless of the protocol used at that the endpoint. Normalized APIs allows you to take advantage of our “one-to-many” integration approach by mapping a single resource to multiple Element instances.

ERROR HANDLING
Errors are returned in a normalized JSON structure providing consistent error codes across all endpoints. If a response returns a message that includes a specific detail about the method call, we send our normalized error code along with any additional data included in the body of the message.

Provided list of normalized error codes:

Screen Shot 2017-10-12 at 2.05.14 PM.png

AUTHENTICATION
Cloud Elements has normalized authentication for each type of authentication used by each endpoint including basic, OAuth1, OAuth2, WS-Security, API Key, and custom mechanisms. We use a normalized API token based approach with user and organization secrets, combined with an Element Token associated with specific authenticated account of the Element. Switching endpoints within a Hub is as simple as swapping out a single Element Token. 

PAGINATION
When a request returns multiple pages of a response, Cloud Elements normalizes the pagination information from the endpoint, allowing the developer to implement normalized pagination code.
There are three main pagination types that we commonly see: limit/offset, page/page size, and cursor-based. All three pagination types can be emulated a cursor-based scheme, which is precisely what we do in the Cloud Elements platform. 

SEARCH
Cloud Elements provides a standard SQL-based query language known as Cloud Elements’ Query Language, or CEQL, that is consistent across each Element. We do the work of transforming the CEQL to the native search language at an endpoint. It is important to note that search capabilities vary significantly across endpoints so searches may be limited if the endpoint does not allow searching of certain fields.


DOWNLOAD THE FULL GUIDE: ANATOMY OF AN ELEMENT


BULK

Your customers demand bulk data operations including asynchronous bulk APIs on each Element, retry capability to work around rate limits, and or/create bulk facade even when the endpoint does not natively support it. For the endpoints that natively support batch or bulk APIs, we can take advantage of those directly, but many do not support this functionality. For these endpoints, we’ve built a custom framework on top of the standard API to create facade bulk actions.

Screen Shot 2018-01-30 at 4.50.56 PM.png

EVENTING
Developers want a standard way to handle events happening within the endpoint. Cloud Elements supports both polling (less efficient) and webhooks (preferred)

Polling: works by querying the endpoint for any objects that have changed within a set polling interval. If the query finds anything, it will return the new or changed data - but this varies vendor to vendor.

Webhooks: provide your application a way of consuming new event data from an endpoint. However, instead of sending repeated requests for new events, you provide the endpoint with a URL which your application monitors. Whenever a new event occurs within the endpoint app, it posts the event data to your specified URL, updating your application in real-time. 

MODEL SCHEMAS
To help reduce your time to market of building integration, we’ve developed one-stop-shop, in-depth API documentation - so your developers don’t have to waste time going to individual vendors’ (e.g. Salesforce) documentation site. 
Our goal is to provide your development teams with a standardized and consistent model experience out-of-the-box. We arm your developers with normalized models for objects and metadata captured for each field.

DISCOVERY APIs & CUSTOM DATA
We provide a comprehensive data discovery service that provides normalized metadata, such as the list of custom field names and types. Additional information, if available from an endpoint, may also be obtained such as: display name, read-only, etc. If an endpoint doesn’t provide discovery service APIs, Cloud Elements will still provide a minimum set of metadata about the given resource (e.g., name and type). Cloud Elements also allows you to discover custom fields (as long as the values are not empty), by supplying an object ID when a native discovery service is not available.

discovery apis.png


OPENAPI SPECIFICATION
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. OAS use cases that Cloud Elements supports includes machine-readable API definition documents with, interactive documentation; code generation for documentation, clients, and servers; and automation of test cases.

MAINTENANCE
We have a team of 15 engineers that is dedicated to maintaining all APIs, versioning, and change management of our catalog of over 130 Elements. We manage over 8000 endpoints with 150 third party partnership agreements - with contractual rights to deliver our service. Our goal is free up your engineering team to focus on your core product and features while keeping integration emergencies out of your backlog.

To learn more about our Elements' robost feature set, get your copy of our guide The Anatomy of an Element below. 

Download the eBook