Identifying API Descriptors

Using descriptors

The first step in our API design method deals with identifying the names we’ll use for all our data elements and actions. We can call these bits of information descriptors because 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 design is to make sure the actual names we use are well understood. It turns out many companies have their own ...