Below the surface of API integration design, explorers (aka developers) will discover critical integration tasks required to fully optimize their app’s integration user experience. With the recent release of the Definitive Guide to API Integrations eBook, we have discovered our own guide to designing and building an API Integration that flows in three primary categories: plan, integrate, test.
Diving in, the first critical step to discovering your API Integration Strategy starts with defining user stories and personas. Write your user stories from the end-users perspective, guiding them with a natural workflow such as: select an endpoint, authenticate, browse objects, schedule and sync. When creating the mock-up of the user experience, consider the best practice of always keeping your users in your app.
Next, the workflow for authentication to each instance of an endpoint can vary greatly depending on which authentication mechanism is supported by that application. Determine the type of authentication mechanism the endpoint will use (OAuth, OAuth 2, SAML, etc) and the workflow required by that endpoint. For instance, you’ll need answers to questions like, “what’s the refresh token process look like for each endpoint and who will you be best manage those keys?”
Discovery APIs for custom and standard object 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 are most relevant to your application.
Mapping and transformation provide powerful customization for your users to integrate their apps of choice, the way that works best for them. Your application may use different formats for data values such as Data, Time, Currency 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.
In the depths of the integration, you’ll end with determining if you need to synchronize data between your application and the endpoint. Many endpoints support webhooks that can be used to simply automate a workflow such as new data being added, deleted or modified. Alternatively polling features can be implemented to handle the same type of work that a webhook would do.