In the previous article we analyzed how the frequency of requests to Tezos Explorer API can be optimized depending on the time between blocks and cycles and demonstrated the most effective approach using this knowledge.

In this article we continue to show you how to get the most out of using TzKT, Tezos Explorer API. Almost every day new bakers, wallets, DApps, exchanges and even various explorers appear in Tezos ecosystem. In this series of articles we will try to help developers to use Tezos Explorer API in more effective way, which we believe will lead to better user experience.

Table of contents

• ✅ Don't request the same data until it actually changes
• ✅ Request only what you actually need
• ✅ Filter data on the API, not on the client
• 🔜 Use pagination carefully

Request only what you actually need

By default, the API returns objects that contain the maximum set of data to cover as many cases as possible and meet the needs of as many users as possible. However, for each particular user and for each specific task, most of the resulting data is redundant because it is simply not used. This leads to inefficient use of network traffic and sometimes inefficient response time.

For that specific purpose TzKT API provides the ability to request only the required data using query parameters ?select= and ?select.values=.

For example, we want to get snapshot levels. We can easily do it using the /cycles endpoint. Although, this endpoint returns an array of objects full of useful data:

[{
    "index": 7,
    "snapshotIndex": 9,
    "snapshotLevel": 2560,
    "randomSeed": "1bcd1d832aff2d72a8d16a9f9e5f994e177e29eac789138b019f0c4a30c4e5ec",
    "totalBakers": 52,
    "totalRolls": 19077,
    "totalStaking": 190989137117557,
    "totalDelegators": 312,
    "totalDelegated": 187846516221396
},{
    "index": 8,
    "snapshotIndex": 14,
    "snapshotLevel": 7936,
    "randomSeed": "4a38061cdab9818e0aa6e05e57fc65b5e80abc53618e82b9ab9a12bbf739c764",
    "totalBakers": 168,
    "totalRolls": 22422,
    "totalStaking": 224673132682556,
    "totalDelegators": 1169,
    "totalDelegated": 215276722522456
}]

However, we only need snapshotLevel. So, by appending query parameter ?select=snapshotLevel to our request /cycles?select=snapshotLevel we'll get what we actually need:

[2560, 7936, 9728, 15872, 20480, 24576, ...]

That's much better, isn't that? We've received only what we need.

In some cases using the ?select= query parameter can help both reduce the amount of data transferred and reduce response time, due to the smaller number of JOIN operations when requesting the database.

Here's another good example of how data selection can affect performance:

URL	Data size	Response time
/originations	176 KB	150 ms
/originations?select=	55 KB	99 ms
/originations?select.values=	42 KB	98 ms

As you can see, you can reach significant performance increase by using the ?select= query parameter.

select vs select.values

As we already mentioned above TzKT API allows making data selection in two ways: select and select.values. Now let's focus on them in more detail.

In both modes, we need to specify a comma-separated list of fields to be included in the response. In case of select mode the response will be represented as a list of the regular JSON objects.

EXAMPLE

?select=address,balance => [ { "address": "tz1abcd", "balance": 1000 } ]

In case of select.values mode the response will be an array of array of values.

EXAMPLE

?select.values=address,balance => [ [ "tz1abcd", 1000 ] ]

To better understand the difference between these two modes, let's look at a couple more examples

URL	Data size
/blocks?select=validations,priority...	320 kB
/blocks?select.values=validations,priority...	70 kB

As you can see, there's a tremendous difference in the data. Obviously, sometimes the difference is insignificant:

URL	Data size
/blocks?select=hash,baker...	151 kB
/blocks?select.values=hash,baker...	136 kB

This depends mostly on the length of the field name and the amount of data contained in the field, so in each particular case it is better to estimate the amount of data and on this basis choose between ease of use and response time.

NOTE

If you select single field, response will be an array of values in both .fields and .values modes.

Conclusion

In this article, we demonstrated how using the ?select and ?select.values parameters we can significantly reduce network traffic and increase performance of your application. If you miss something in the Tezos API, please contact us and we'll do our best to help you!

What's next?

This is the second article of series "Tezos Explorer API Best Practices". In the next article we'll talk about data filtering in API requests.

Cheers!