Streamtime's API v1 was initially developed and released almost 8 years ago, when the Streamtime product had fewer features and data than it does today. As such, once you've connected, v1 returns all the information, all the time — whether or not you need it. While that might sound like a good idea, once you start working with large reports, you end up wasting a lot of time and resources retrieving information that you don't need.

The v2 API improves performance by only returning the information you request when you are searching. This gives both a speed improvement to the response time, as well as reducing the size of the data transferred to you. Hence, the schema and structure of the API has been fundamentally changed: v2 now returns much less as a default, with the ability and flexibility to decide what additional info you might need for your custom reports and functionality. ⚡️

Let's take searching for contacts as an example. With the default parameters, we only receive the information directly related to the contact. We can still see what company they belong to (ID 137), but as you can see in the request below, both company and companyLeadUser return null because we haven't requested them.

That's where additional data comes into play. As part of the query parameters to the search, we can now specify what additional data we want returned alongside the main record. For the case of contacts, we can also request the Company and the Lead User of the Company. In this example, I don't care about the companyLeadUser, but I want the company information for my report.

By making these changes, Streamtime is now able to better construct the data for your reports to be able to return the data as quickly and efficiently as possible. With small searches, you might not notice this change — but when you're looking for lots of data, the speed optimisation is significant.

Another optimisation that we have made is to remove the statistics object from the search route's response. When you're using pagination to return several thousand records, Streamtime was generating the statistics for you on every request. Given that the statistics don't change from one page to the next, it was wasting a lot of time and resources generating something that was almost certainly being thrown away after the first page.

In addition to building the v2 API, we made some performance improvements to v1. One of the changes we made was to make it possible to turn off statistics. If you're after a quick win to get some additional performance from the API, this is a minimally intrusive way to update your v1 reports if you aren't using the statistics object. Don't worry though, if you don't include this parameter, Streamtime will default to sending statistics so that it is backwards compatible.

In the v2 API, we've removed statistics entirely from the search route, as we have the more powerful column_series and time_series requests. With these requests, you can specify exactly which fields you are interested in, how you want them calculated (count, sum, average, or all of the above), and even return statistics from multiple data sources in a single request (eg logged hours + invoice totals + quote totals for a given month).

As well as these major changes to how we perform searches, we've also updated the API to enable features that have been built in the UI but hadn't been able to be put into the API for backwards compatibility reasons.

We encourage customers who are currently connected to v1 API for their reporting to explore refactoring using v2. At scale, some v1 reports may experience timeout issues due to the size of the queries. v2 solves this issue and returns exactly what you want, and nothing more — all faster. We'd love to hear what you think while v2 is in beta: reach out to help@streamtime.net with feedback.