Today, we wanted to talk about OpenAPI Enumerators. Along with each API we publish to the Streamdata.io API Gallery, we provide an example command line CURL command that you can use to proxy and stream the potential API endpoint. Using OpenAPI definitions for each API allows us to append any headers, path, or query parameters to the example curl command. Ensuring the example is as ready for execution as we can possibly make it. Here is an example blockchain API call for identifying specific pools.
All you have to do is provide values for each variable, and you should be able to run this at the command line. Finding your Streamdata.io token is pretty straightforward (and free), but knowing what to put into the other values can prove more difficult. Hopefully, each APIs documentation provides examples of what data should be included, and provide lists of any values that are common, but sadly many do not. In this example, you have X bitcoin pools you can choose from for the {pool_name] values:
{
"Unknown": 44,
"BW.COM": 4,
"BTC.TOP": 69,
"BTCC Pool": 22,
"AntPool": 90,
"ViaBTC": 79,
"BTC.com": 169,
"SlushPool": 63,
"58COIN": 7,
"F2Pool": 30,
"BitFury": 9,
"Bitcoin.com": 8,
"BitClub Network": 16,
"GBMiners": 5,
"BitcoinRussia": 3
}The remaining format value in the query string should just be JSON, otherwise it just shows the HTML representation (aka the web page). Without knowing these Bitcoin pools, users have a difficult time actually making an live API call. Even if they get past the authentication required for both the Streamdata.io, and the API providers side of things, there could still be any number of header, path and query parameters they need to figure out. This is where the enum property in the OpenAPI specification comes in handy, allowing API providers to provide a machine readable list of potential values that can be used to make each individual API call.
OpenAPI enumerators (or enums) providing the missing dimensions that API consumers will need to actually make a valid API call at execution time. In this case it is Bitcoin pools, but often times it is a list of states, countries, stock tickers, and other common, or not so common values needed. When possible, we add enums to each OpenAPI we are including in the Streamdata.io gallery, but this takes a significant amount of work, and is something that would be better conducted by API providers. No matter who provides these enums, they will continue to be essential when it comes to providing all the dimensions required to fully realize, and put to use any API -enabling consumers to make simple polling, as well as streaming requests of API resources.
Photo credit: Angelo Juan Ramos