Design and Build Great Web APIs

Identifying Your API Descriptors

The first step in our API design method deals with identifying the names we’ll use for all our data elements and actions. I call these bits of information descriptors since they’re meant to describe the contents of the data elements (for example, companyName) and describe the action a developer would be taking (for example, approveUser). While the actual name we use for this isn’t too important, what is important is that we’ll be using the same name (descriptor) for both data and action identifiers. Often we spend a great deal of time covering the names of data elements but don’t always spend as much time on the names of the actions.

Another important aspect of focusing on the descriptors in our API ...