Using Discovery APIs to Discover Custom and Standard Objects

By David Honan in How-To, Cooperative Apps Posted Nov 18, 2014

A cooperative app experience uses APIs to connect your application seamlessly with the cloud services used by your customers. By letting the users of your app share account data from Salesforce API or contact data from a marketing automation system like HubSpot API, or even share files with the Dropbox API, you’re creating a cooperative experience. A cooperative app is the seamless data sharing interaction between technologies that will delight your users.

When integrating to application endpoints such as CRM, Marketing Automation or Finance systems your app will need to discover the standard and custom data objects and fields used by your customer’s instance of the endpoint.

Before we dive right in, I’d like to welcome you back to the Cooperative App series. So far my colleagues have covered the 10-Step overview, talked about pre-work required to design an API Integration, how to optimize user experience and the mechanics of authentication.The next three parts in this series (Discover Data Objects, Map Data and Transform Data) will give you the ammo you need in designing API Integrations, making your app one step closer to a truly Cooperative App.

THE DISCOVERY PROCESS

In discovering custom and standard objects, there is a 3-step process to follow with APIs. First you need to know your objects in your app, or perhaps more importantly prioritize the objects that need to talk to other cloud services. Which data objects are required to create a really cooperative app experience for your end users? Focus on the objects that will make your cloud integration really work. In this blog I’m going to reference an example by using common objects like person (which could be a contact) and location (which could be address, country, or neighborhood). From there, we’ll talk through standard objects and custom objects, and what to do with each.

STEP 1: IDENTIFY RELEVANT DATA OBJECTS WITHIN YOUR APP

Identify which of your application’s data objects are relevant to the data you’re targeting at the endpoint(s). In most cases, you will only be integrating a subset of the data objects and fields from the endpoint. Your application’s data model will provide the basis for determining the data you’re interested in integrating with. You will then identify the standard objects at the endpoint that you will be integrating to your app. In our example, let’s stick with two objects that an app is using: person and location.

STEP 2: DISCOVER STANDARD & CUSTOM OBJECTS

Your integration will likely need an automated means to discover custom objects and fields at the endpoint if you plan to support the integration and mapping of custom data. Since the majority of SaaS application endpoints (e.g., CRM, Finance, Marketing) make extensive use of custom data fields and objects you will likely need to discover the data structure at the specific instance of the endpoint in addition to understanding the standard data objects. A standard object will persist across multiple instances of an endpoint but custom objects and data fields will only exist for a specific instance of an endpoint (i.e., a specific authenticated account of an endpoint).

There’s two types of discovery mechanisms. Some endpoints such as Salesforce.com, Sugar and Eloqua provide discovery APIs that you can use to programmatically discover all the fields contained within an object, giving you the ability to programmatically discover standard and custom objects and data fields. You’ll need to use these discovery APIs to find the equivalent objects in a cloud service you’re integrating to. By using a discovery API, you can discover all the fields related to the object you placed a discover API call against.

To retrieve all of the objects that exist for a given Element, call the /objects API:

Discovery APIs

 

Alternatively, if the endpoint doesn’t provide a Discovery API you will need to provide a mechanism to the user in order to retrieve the complete data structure of the object including custom fields. For RESTful endpoints you can issue a GET with the object ID for a fully populated custom object and the payload will return the complete list of fields. In some cases you can issue a GET with the object name to register a new custom object, then you can call the discovery api with the id to get a complete list of fields.

Here are the common API calls with api-v2 environment.

1) Register the discovery API for the product objectDiscovery APIs

2) Register a new object called "people"

Discovery APIs

To retrieve the metadata for a specific object, call the /objects/{objectName}/metadata API:

Metadata API

 

STEP 3: START TO STANDARDIZE ON PATTERNS

The beauty of taking the extra effort to discover data objects your app is creating, is that once you’ve collected enough data and evidence, you can start to figure out patterns your customers create. Those patterns are what you can use to automate the process (or what I like to call ‘Automagic’). From those patterns you can essentially create standard API calls on custom objects.

If you can automate the crap out of this discovery stage, with really fast API calls – your app will surely be on the fast track towards a cooperative app. Think about it. The ultimate flow for an app (from a system administrator’s point of view) is to click on a button, authenticate in with my own credentials, use your recommendations for mapping my standard data to standard fields, and then use the pick-list to map custom data to custom fields.

Field Mappings for your end user should look like this:

Standard field mappings

You can (and should!) put the honice on the system administrators to map out the custom objects. Your customer’s system administrators are a wealth of knowledge, and they’ll know better than anyone how to discover and treat custom objects.

Next in the series, we’ll take a deeper dive into mapping custom data, and then transforming data in your applications API integration. Until then, if you need help creating a killer cooperative app, download our eBook.

the-definitive-guide-to-API-Integrations-eBook

cooperative-app-series-banner