To build a seamless user experience for your customers, it’s essential to offer pre-built, pre-orchestrated integrations to high-demand complementary applications (e.g., CRM, Finance, Marketing apps).
One of our customers put it as, "we're the tail. We don't wag the dog." This gets at the idea that given the expanding app ecosystem (more competition + more apps to integrate to...), customers will only pick companies that seamlessly connect to apps they're already using. No one wants to buy more new software just so they can use your app.
Unfortunately, building this cohesive customer-oriented experience requires more than just point-to-point integrations. And it’s bigger than simply writing directly to the API.
Below the surface of writing to an API, developers are faced with many complexities - right now, let’s focus on search and browsing (aka giving your users the ability to find and select the data they need from the integration endpoint.)
This blog post is a follow-on to our updated Definitive Guide to API Integration. Download the full guide for more in-depth content on integration best practices, from pre-build to post-build, or check out the blog series.
User Stories For the Search and Browse Function of API Design
When it comes to API design, you first need to have the data mapped and have ensured the values can be transformed. The next step is to present the user with a way to search and/or browse as they wish.
You’ll need to identify the data objects from the integrated endpoint (resources) that your app will present to the user, such as customers, contacts, products, and people. Then, consider if your users will need to interactively engage with data in the endpoint to perform CRUD(S) operations.
Some of the interactions could include selecting files or data records or updating or deleting data from the endpoint. Check out these common examples:
- “As a cloud document storage user (e.g. Dropbox or Google Drive), I want to browse by folders and find my documents so that I can load them into the app that’s integrated to the service.”
- “As a CRM user (e.g. Salesforce), I want to browse customer accounts by company name so that I can easily sort and find the right account to sync with the integrated app.”
- “As a Finance user (e.g. QuickBooks or Xero), I want to search for paying and non-paying customers so that our app can stay in sync with my reports.”
When you’re planning and defining the API design to enable search and browse functionality, you’ll need to keep the following factors in mind:
- The search functionality provided by APIs from leading SaaS applications varies dramatically. Make sure to research the offered search capabilities for each endpoint to determine if you need to take a least common denominator approach or write specialized search integrations to each endpoint. For instance, Salesforce has a very robust query language (SOQL) that supports a powerful set of queries, while other endpoints provide a fraction of the functionality.
- The second area of variability is how to page the results returned from each endpoint. The search function of an endpoint should be set up for pagination. You have to manage precisely how paging will operate in this browse function if you want your app to bring back any type of response.
At its core, integrations = data operations, and with any operation, you only want to work with or change the specific data that you care about. To do this, you need search/query, which each API implements differently. Given these obstacles, you’ll have to become an expert for each target application’s API every time you want to query your data.
If you’re not already using an iPaaS, you’ll need to watch out for this issue ahead of time when you’re coding your integration. Or, if you are using (or looking for) an iPaaS, you should consider looking for one that normalizes search so you can reduce the heavy load on the development team.
Ready to learn more about best practices for building integrations (from defining user stories to API maintenance)? Check out our Definitive Guide to API Integration.
Even more? Read the next post in the series: webhooks vs polling.