COOPERATIVE APPS SERIES
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 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.
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.
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.
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.
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.
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..
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.