Reducing Friction For API Developers With Enums In API Definitions

October 19, 2016

I am going through the Oxford Dictionaries API, learning about this valuable resource. Their onboarding process for registration, and learning about what the API does using interactive documentation, is very smooth. One of the things that really cuts the rough edges off learning about each API are the enums that are available for each path.

The parameters required for making calls to many of the paths, like language and country, have their enum values populated as part of their API definition. I look at numerous OpenAPI Specs in the course of my work and they rarely have values present for enum, providing critical default values for developers to use--eliminating some often serious frustration.

Not having the right values available when making even the simplest of API calls can be a significant point of friction when trying to get up and running using an API. While it may seem like a small thing, the work the Oxford Dictionaries API team has put into this level of detail for their API definitions will go a long way towards making their API resources more accessible and usable.

Read more...

Previous Article
What Are Your Intentions With My API?

While it can be easy to bash on API providers for being tight with their API resources, it can be very dif...

Next Article
What Is More Important? Helping New Users Be Aware Of APIs Or Pushing Concept Forward?

This is a topic that has come up in several discussions lately and is a topic I struggle with on a regular...