10 Step Guide Series: How to Design an API Integration
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 Dropbox, Google Drive, Salesforce.com, 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.
Follow this 10-step guide, reflecting a common pattern for interactive 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.
Step 1: OPTIMIZE USER EXPERIENCE
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 API 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.
STEP 2: SECURE AUTHENTICATION
Manage the workflow for authenticating to each instance of an API endpoint that your users are connecting 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.
STEP 3: USING DISCOVERY APIs
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.
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 integration end-points provide automated data 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.
STEP 5: MAP DATA
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 api endpoint that is connected with your app.
STEP 6: TRANSFORM DATA
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 api endpoint that your app is connecting with.
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.
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.
STEP 9: Events & Synchronization
Determine if you need to synchronize data between your application and the endpoint. Many integration 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.
STEP 10: LOGGING and Api Monitoring
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.
Api Integration Maintenance
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.
Learn more from this 10 Step Guide blog series:
- BEST PRACTICES FOR DEFINING API INTEGRATION USER STORIES
- AUTHENTICATION: 5 KEYS TO BUILDING API INTEGRATION
- USING DISCOVERY APIS TO DISCOVER CUSTOM AND STANDARD OBJECTS
- DATA MAPPING | 5 STEPS TO CONQUER CUSTOM OBJECTS & FIELDS
- HTTP VERBS DYMYSTIFIED: PATCH, PUT, POST
- API DESIGN: HOW TO IMPLEMENT SEARCH, BROWSE, SELECT
- WEBHOOKS VS. POLLING: SYNC YOUR APPS
- THE 5 PITFALLS OF API MONITORING