By David Honan in GET/technical Posted Nov 18, 2014

Step 3: Use Discovery APIs [Blog Series]

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.

Custom and Standard Objects

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 API endpoint.


Before we dive right in, I’d like to welcome you back to the Getting Started with API Integrations series. So far my colleagues have covered the 10-Steps 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.



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.


Are all of your application's data objects relevant to the data you’re targeting at the endpoint(s)? To determine the data you’re interested in integrating with, turn to your app’s data model to identify the standard objects at the endpoint that you will be integrating to your application. In our example, let’s stick with two objects that an app is using: person and location.


If you plan to support the integration and mapping of custom data, you’ll need an automated means to discover custom objects and fields at the endpoint. In addition to understanding the standard data objects, you’ll likely need to discover the data structure at the specific instance of the endpoint in the majority of SaaS application endpoints. While a standard object will persist across multiple instances of an integration endpoint, custom objects and data fields will only exist for a specific instance.

There’s two types of discovery mechanisms. Some endpoints such as, 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:

/objects API for elements

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 objectRegister the discovery API for the product object

2. Register a new object called "people"

Register a new object called "people"

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

Retrieve the metadata for an object: call the /objects/{objectName}/metadata API



Once you’ve collected enough data and evidence, you can start to figure out patterns your customers create. You can then use those patterns to automate the process. 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 onus 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, check out the Definitive Guide to API Integration resource.


   Read Step 2: Authentication .  Read the Next Steps