We are spending a lot of time this week down in the weeds of the APIs we profile for the Streamdata.io API Gallery. We are studying the different parameters API providers are using as part of their API design strategies, looking for patterns in how they are making data available, even down to the types of values, or enumerators (enums) can be put to use. As part of our work, we find the enumerators for any parameter to be just as, or more important that the parameter itself. As we profile each API, if an API provides lists of valuable enumerators as part of their operations we like to document it as part of our discovery efforts. This week, as we were looking at the shipping aggregator Shippo we came across their list of shipping carriers to help developers refine their API queries:
– apc_postal – Enumerator for APC Postal
– australia_post – Enumerator for Australia Post (also used for Startrack)
– aramex – Enumerator for Aramex
– asendia_us – Enumerator for Asendia
– borderguru – Enumerator for BorderGuru
– boxberry – Enumerator for Boxberry
– bring – Enumerator for Bring (also used for Posten Norge)
– canada_post – Enumerator for Canada Post
– correios_br – Enumerator for Correios Brazil
– correos_espana – Enumerator for Correos Espana
– collect_plus – Enumerator for CollectPlus
– couriersplease – Enumerator for CouriersPlease
– deutsche_post – Enumerator for Deutsche Post
– dhl_benelux – Enumerator for DHL Benelux
– dhl_germany – Enumerator for DHL Germany
– dhl_ecommerce – Enumerator for DHL eCommerce
– dhl_express – Enumerator for DHL Express
– dpd_germany – Enumerator for DPD Germany
– dpd_uk – Enumerator for DPD UK
– estafeta – Enumerator for Estafeta
– fastway_australia – Enumerator for Fastway Australia
– fedex – Enumerator for FedEx
– gls_de – Enumerator for GLS Germany
– gls_fr – Enumerator for GLS France
– globegistics – Enumerator for Globegistics
– gophr – Enumerator for Gophr
– gso – Enumerator for GSO
– hermes_uk – Enumerator for Hermes UK
– hongkong_post – Enumerator for HongKong Post
– lasership – Enumerator for Lasership
– mondial_relay – Enumerator for Mondial Relay
– new_zealand_post – Enumerator for New Zealand Post (also used for Pace and CourierPost)
– newgistics – Enumerator for Newgistics
– nippon_express – Enumerator for Nippon Express
– ontrac – Enumerator for OnTrac
– orangeds – Enumerator for OrangeDS
– parcel – Enumerator for Parcel
– posti – Enumerator for Posti
– purolator – Enumerator for Purolator
– rr_donnelley – Enumerator for RR Donnelley
– russian_post – Enumerator for Russian Post
– sendle – Enumerator for Sendle
– skypostal – Enumerator for SkyPostal
– stuart – Enumerator for Stuart
– ups – Enumerator for UPS
– usps – Enumerator for USPS
– yodel – Enumerator for Yodel
Providing enumerators as part of API documentation saves developers a great deal of time when it comes to understanding what is possible with an API. Ideally, these enumerators are part of your OpenAPI definition, but at the very least, you should be providing a known list of all enumerators for all API parameters. Don’t make developers go looking the values they should be passing along with each API call–go the extra mile when it comes to documenting your API.
We are going to profile all of the enumerators that Shippo provides, and index them as part of our overall enumerator database. Eventually we are going to publish this database to the Streamdata.io API Gallery, dedicating a section of the gallery to enumerators, which will allow us to track on the common values used across APIs, while also enabling the browsing and discovery of APIs that support specific enumerators, like shipping carriers, stock tickets, and other common values. Making it easier for us to find different types of APIs that are related, based upon APIs sharing common enumerators.
