The 10 Step Guide to Designing an API Integration

By Hannah Shain in How-To, Cooperative Apps Posted Sep 2, 2014


Product Owners and App Developers are frequently tasked with designing API integrations between their apps with the cloud services used by their customers, partners or employees.  Integrating your app with cloud services such as DropboxGoogle,  Jira and Quickbooks can provide your users with a “cooperative” experience in which they can seamlessly share data between your app and the other cloud services they use on a daily basis. This new era we’re entering envisions cooperative, or connected, applications via cloud-based API integrations. 

cooperative-app-series: guide to API integrations

Follow this 10-step guide, reflecting a common pattern for interactive API integrations between your app and other cloud services. Let us know how this works for you and other ideas you have in how we can improve the model.

guide to API integrationsSELECTION

Where in your app will the user select the service endpoint(s) they want to connect with your application? Are end-users or administrators going to be setting up the integration? Is it a one time setup or is on-going interaction required? These and many other factors will drive the optimal interface to present your users in selecting the services they want to connect with your app. 

AUTHENTICATIONguide to API integrations

Manage the workflow for authenticating to each instance of an endpoint that your users areconnecting with your app. Determine the type of authentication mechanism the endpoint will use (e.g., OAuth, SAML) and the workflow required by the endpoint.  Do you need to keep the authenticated instance active?  What’s the refresh key process for each end-point and how will you manage the keys.

guide to API integrations


Many services provide a method to discover the objects and data fields at the endpoint to provide the data structure, field names and formats that need to be mapped into your application. You’ll need to determine which objects and data fields that are relevant to your application. Often this is a subset of the available data at an end-point.


guide to API integrations

Many SaaS services support custom data objects and data fields that your customers would like to share with your application.  Consider if your integration design needs to accommodate discovery and mapping of these custom data objects to your apps’ data model. Many end-points provide automated discovery of custom objects but with others you may need to provide a manual means for your users to map these objects into your application.


Generally data mapping entails  a two-step process.  The first –  provide a default mapping from an endpoint’s standard data structure into your application’s data structure.  The default mapping saves your users time by pre-mapping obvious data fields such as name, address  , postal code, etc.  The second step is to provide your application’s users with the ability (generally through a UI)  to map custom data objects and fields into your application. Through this UI you may also consider providing the ability to override your default mappings.  Your application will require the ability to persist these data mappings for each instance of an endsspoint that is connected with your app.

guide to API integrations


Your application may use different formats for data values such as Date, Time or other forms of data. Transformation services may be required to translate the data between your app and the endpoint’s data structure to ensure integrity of the data. As with data mapping your application will need to persist the transformations for each instance of an endpoint that your app is connecting with.

guide to API integrations


Determine which methods your application needs to execute against each data object (Create, Retrieve, Update, Delete, Search). Consider which app will be mastering the data vs. consuming the data to avoid conflicts and having to manage more complex data synchronization scenarios. Often you can start with a read-only integration and then introduce update and delete methods as you mature your integration.

guide to API integrations


Will users need to interactively engage with data in the endpoint to perform the CRUD(S) operations? Interactions may include selecting files or data records, updating or deleting data from the endpoint to provide a seamless integration experience for the user from within your application..



guide to API integrations

Determine if you need to  synchronize data between your application and the endpoint.  Many endpoints support webhooks that can be used to simply automate the workflow keeping your application up-to-date with changes (events) at the endpoint  such as new data being added, deleted or modified.


How will you support and manage the integration? You will need to capture usage and log data to support the integration to keep your operation team in the know. Determine how to handle alerts and notifications from the endpoint regarding service outages, API changes, etc.

Lastly, although this is not a step in the integration process, you will need to consider how to maintain the integration. APIs change frequently, so develop a strategy now for staying on top of changes introduced by the services you are connecting. This includes managing version control, to ensure your integration doesn’t break as changes are introduced.

Meanwhile, if you need help creating a killer cooperative app: Try Cloud Elements. Download our eBook for a in depth look at designing API integrations.