API Design: How to Implement Search, Browse, Select

By Mark Geene in GET/technical Posted Aug 13, 2015

API Design is about building apps with pre-built, pre-orchestrated integrations to complementary applications (e.g., CRM, Finance, Marketing apps). These apps are in high demand by today’s consumers. But it’s more complex than point-to-point integrations. And it’s bigger than simply writing directly to the API. API-integrations-icebergBelow the surface of writing to an API, developers are faced with complexities including authentication, data transformation, logging and cache management. The Cooperative App Series covers many of these ‘below the surface’ challenges. Today I’d like to continue the series, now focused on search and browsing: giving your users the ability to find and select the data they need from the integration endpoint.

Three User Stories for the Search & Browse Function of an API Design

Once you’ve mapped the data and ensured the values can be transformed, the next logical step in API design is to present the user with a way to search and/or browse the data that they wish to access. Identify the data objects from the integrated endpoint (resources) that your app will present to the user such as customers, contacts, products and people. Consider if your users will need to interactively engage with data in the endpoint to perform CRUD(S) operations. Some of the interactions may include selecting files or data records, or updating or deleting data from the endpoint. Here are three scenarios we can relate to as app developers:

  1. As a cloud document storage user (e.g. Dropbox or GoogleDrive), I want to browse by cloud folders and find my documents, so that I can load them into the app integrated to that service.

  2. As a CRM user, 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.

  3. 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.

There are a few areas to consider when planning and defining the API design to have search and browse functionality: Binoculars-2

  1. The search functionality provided by APIs from leading SaaS applications varies dramatically and these limitations will impact the type of functionality you can offer across endpoints. It is important to research the search capabilities that are offered first to determine if you will 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.  

  2. Another 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. Paging is a big factor in how users can search and find the data they are looking for - and a big reason why apps are choosing to work with Cloud Elements for the normalized access to paginated resources across all endpoint. You have to manage precisely how paging will operate in this browse function if you want you app to bring back any type of response.

When apps and cloud technologies work together, with pre-built, pre-orchestrated integrations, that’s cooperation. Easing the process for users to browse and search your app’s integrations yet another crucial aspect of creating a Cooperative App. Next in the series, we’ll discuss how to to design events and workflows to enable on-going synchronization between your app and the other cloud services you are integration. Until then, if you need help creating a killer cooperative app, Try Cloud Elements.


Ready to design a cooperative app today?
Get the eBook.