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 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.

Using Schema.org as a validating source

The work of picking descriptors for our API is the process of validating that the data elements and actions have been provided names that are normal for the target audience using the API. For this reason, we can refer to this work as normalizing the identifiers. The trick is to find something everyone agrees on to act as the reference list of terms. Often companies already have a published glossary of common terms. Many companies working in the fields of banking, insurance, healthcare, and other large professional marketplaces have a set of terms managed by a standards body in the related field. For example, the banking sector has a set of information standards known as the Banking Industry Architecture Network (BIAN). And the Fast Healthcare Interoperability Resources (FHIR) standards pertain to the healthcare industry in the United States. Many other science and engineering fields have similar dictionaries or glossaries that can be used as a validating source when normalizing API identifiers.

To keep things simple for our example, we’ll use a general validating source called Schema.org. It’s described as “a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet, on web pages, in email messages, and beyond.” Schema.org is a joint effort by Google, Microsoft, Yahoo, and Yandex to create a set of shared vocabularies that can be used by a wide range of web developers. We’ll use Schema.org for this API because it’s a handy and widely available set of terms. In our own organization, we may already have a set of terms we commonly use, and we may also have some vocabularies managed by outside organizations that we can use. The important thing to keep in mind is that we should normalize our API identifiers against one or more of these well-known vocabularies.

Normalizing the Onboarding API identifiers

Now, we’re ready to review our current API design document and normalize it against our validating source, Schema.org. First, let’s take a look at our Onboarding API workflow document again: