Identifying API Descriptors
Learn how to identify descriptors when designing an API.
We'll cover the following...
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 vocabulary that they use every day. Often these terms take the form of acronyms or abbreviated terms. For example, a customer record might be referred to as a “CustRec” in meetings within the company, and everyone understands what that means. This is a common aspect of all groups of people; even teams within a company may have their own shorthand or unique terms for objects and actions.