In today’s digital economy, your data’s value will be limited and muted if it remains siloed within individual business systems. The power of digital transformation can only be unleashed when data flows freely between key business systems. The connective tissue between these applications is often APIs (Application Programming Interfaces). These computing interfaces are the conduits through which data is passed into analytics and business intelligence platforms to power reports, dashboards, alerts, apps, predictive models, and so on. Without reporting APIs, it would be difficult, if not impossible, to properly manage, assess and optimize the performance of fast-moving digital businesses.
Reporting APIs create an interesting interdependency between application providers, their customers, and third-parties such as analytics vendors. At the center of this three-party relationship is the end customer, which wants the right data in the right places at the right times. In order for this to happen, you need a robust, reliable reporting API. If a business system’s API doesn’t allow an analytics vendor to extract the data in the manner in which the end customer requires, everyone loses. The end customer isn’t happy, and both of the other parties could end up losing their business.
Fortunately, more software companies are realizing reporting APIs are an essential aspect of their product strategy and offerings. The easier they make it for third-party developers to access the required data, the better it is for all three parties involved. Support costs go down. Mutually beneficial partnerships are formed. Data-driven innovation can occur. Customer satisfaction goes up. Products become stickier. Renewal rates and revenue increase.
WHAT IS A REPORTING API?
Before you say “we’ve got an API for that,” I think it’s important to clarify what a reporting API is because there are different types of APIs. Some APIs are focused on administration tasks such as adding or deleting users and groups, which don’t typically align with reporting tasks. Another set of APIs provides bulk data operations for pulling down large amounts of data. With these APIs, the third-party developer is responsible for recreating the metrics from the downloaded datasets, which can introduce consistency issues. A reporting API enables the third-party developer to pull precise results to answer specific questions and is usually powered by a query language or metric/dimension mapping.
WHAT MAKES A REPORTING API ENTERPRISE-GRADE?
Whether you’re evaluating the openness of a new business application or evaluating your own existing reporting API offering, it is helpful to understand what makes a reporting API enterprise-grade. Having built hundreds and hundreds of API connectors for its customers, Domo has gained a wealth of experience in working with various reporting APIs—some that are really good and others that aren’t so good (full disclosure I work for Domo). To gain a deeper understanding of what constitutes an enterprise-grade reporting API, Andy Beier, Domo’s VP of Cloud integration, outlines the following requirements:
- REST Architecture: Even though REST (Representational State Transfer) has mostly replaced SOAP (Simple Object Access Protocol) as the preferred approach for APIs, some legacy platforms are still stuck on SOAP. REST is much easier for developers to work with, especially because it supports the lightweight JSON format rather than the bulky XML format that SOAP requires.
- OAuth 2.0 Authentication: One of the main advantages of this open data-sharing standard is it enables third-party developers to access data without needing the customer’s credentials (username/password). Customers can authorize the specific data the developers access via revocable tokens. In addition, the developers can be limited to just read-only access, which is all they need (and want) for reporting purposes.
- Delta Approach (What’s Changed): To streamline the size of payloads, reporting APIs should enable third-party developers to easily discover what’s changed since their last download. For example, rather than re-downloading the current list of contacts from a CRM system, the API could instead provide a smaller update on which contacts were recently deleted or modified.
- Pagination Strategy: Depending on the API request, a single payload could have millions or billions of rows. Downloading these large data files can introduce performance issues so pagination in which the file is broken up into “pages” becomes important. With a meaningful pagination strategy in place, developers can start working on the job as it streams in before it has fully downloaded.
- Gzip Compression: A simple way of reducing the amount bandwidth that’s required by each request is to require gzip compression, which can significantly reduce the file size of the payloads. Beier estimates less than 50% of the reporting APIs currently take advantage of this performance-enhancing feature.
- Webhooks: A webhook is an event-triggered HTTP callback that sends data to a third party when a specific event occurs. These updates are fairly lightweight and potentially high volume. A third-party developer will subscribe to specific events they want to monitor via webhooks. A push-based webhook framework can be used to complement your pull-based API strategy.
In addition to these key technical aspects, a reporting API also needs to be soundly managed to be enterprise-grade. Rather than just launching a new reporting API and expecting everything to run smoothly, forward-thinking organizations recognize more must be done to ensure the long-term adoption and success of their reporting APIs. Beier identified four key areas that can up-level your reporting API:
- Update Strategy: When changes are planned for an API, it’s important the developer community is given ample notice so it can mitigate reporting disruptions. If an existing API is being replaced by an entirely new one, companies should offer third-party developers up to six months to run them concurrently before needing to migrate to the new API. In addition, whenever a new API is introduced, serious consideration should be given to feature parity and backward compatibility.
- Documentation: Third-party developers need thorough documentation on the reporting API. One of the key features of any documentation will be easy-to-follow examples with how-to instructions that are based on accepted best practices. In addition to covering topics such as supported HTTP verbs, HTTP headers, compression, and authentication, third parties also need developer sandboxes and API explorer tools to build and test their API requests.
- Support: When a problem occurs with the API, third-party developers need a status page to know if the API is currently experiencing any issues. They also need a support desk where they can go for help with potential issues. Today, Beier notes most vendors provide no mechanism for third parties to inform them when something is wrong. He estimates only 10% of reporting APIs offer adequate support.
- Internal Usage: One way to prevent or anticipate major issues with the reporting API is for the vendor to mandate its internal teams to use the same API. Unless you’re eating your own dog food (or sipping your own champagne), you have less visibility into how your reporting API is performing and how it could be improved.
Integration between business platforms is no longer optional, and APIs are essential to enabling meaningful digital transformations. A reporting API represents an essential data conduit that can feed multiple downstream processes, applications and tools. Without adequate reporting APIs, organizations will struggle to get the insights they need to run their business and improve their performance.
For example, if you turn on a faucet in your house, you expect a steady stream of water to flow out of it. However, if the water is dirty, sporadic or not the right temperature, you won’t be able to put it to effective use. Your company can’t afford to hold back its customers with a weak reporting API that leaves them thirsty for information and insights. APIs are more than just computing interfaces, they’re extensions of companies’ products and brands. They need to be treated as such so the data can be used to drive greater value for everyone involved.
originally posted on forbes.com by Brent Dykes