Application Integration

Shipping Carrier Enumerators From Shippo

We are spending a lot of time this week down in the weeds of the APIs we profile for the 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 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.

AI in Finance White paper - Shippo
**Original source: blog