API Design: How to Implement Search, Browse, Select

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

Step 8: Browse [Blog Series]

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 Events and Synchronization

Below the surface of writing to an API, developers are faced with complexities including authentication, data transformation, logging and cache management. This 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

When it comes to API design, you need to have the data mapped and ensured the values can be transformed first. Then the next logical step is to present the user with a way to search and/or browse as they wish.

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 folders and find my documents, so that I can load them into the app integrated to that service.

  2. As a CRM user (e.g. Salesforce), I want to be able 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.

Next, there are a few areas to consider when planning and defining the API design to have search and browse functionality: API search and browse functionality

  1. The search functionality provided by APIs from leading SaaS applications varies dramatically. Make sure to research the search capabilities that are offered 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.  

  2. 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.  big factor in how users can search and find the data they are looking for is known as paging. It’s 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 ongoing 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 build an Api integration of your own? view the answers you need in one place with our online resource.

Read Step 7: CRUD(S)  Read Step 9: Events and Synchronization