In my last piece, I talked about the importance of not overlooking the behavioral influence of software templates. The conclusion was that our output is influenced by our tools whether we consciously are aware of it or not. Therefore, we could continue to trudge on in ignorance and wonder why things aren’t working out as intended. OR we can design our environments to more easily achieve our governance outcomes.
An OpenAPI description has become the most common way to express RESTful and RESTish API designs. As a result, a wide variety of API tooling presents an OpenAPI default to a developer beginning a new design. Unfortunately, this default is usually a lowest-common-denominator, stripped-down suggestion that does little to encourage company-common practices.
What kinds of prompts could an API Center of Excellence/Enablement, API Governance, or enterprise architecture group consider putting in their default template?
Versioning
In its research (paywalled, unfortunately), Gartner identifies not one, not two, but five different ways an API could be versioned:
- API Evolution, or only allowing for additions to an API
- Root namespace URI versioning (
https://api.example.com/v1/resource) - Resource-level URL versioning (
https://api.example.com/resource/v1) - HTTP content header versioning (
curl -H "Accepts-version:1.0" https://api.example.com/resource) - HTTP query parameter versioning (
https://api.example.com/resource?version=1)
Believe it or not, there are even more ways to version an API than that! And one way isn’t superior to another method. Yet, to manage the cognitive overhead of working with many APIs, it is important to create designs with consistent versioning behavior within a common domain, like an organization. A new member to that domain, when presented with a template, shouldn’t have to guess which approach is desired in their new context.
The OpenAPI template should demonstrate the versioning method preferred by the organization. It should not be up to the designer to recall best practices from a separate correspondence in order to do the right thing.
Better Descriptions
Similarly, how many times have you been reading documentation, like that generated from an OpenAPI description, and you’ve come across something like this:
name: userId
description: the Id of the user
While that might be technically correct, it is also the bare minimum way to describe an important piece of information. The writer might have not bothered with a description since it doesn’t convey much more than what could be gleaned from the name.
In a previous role, we defined a series of characteristics that makes a compelling, worthwhile description.
| Characteristic | Details | Examples |
|---|---|---|
| Context | Detailed business context explaining what the data stands for and its expected usage | “A userId represents individuals and business entities that either (1) have active accounts or (2) are in the pre-sales pipeline.” |
| Disambiguation | Explains terms not commonly used | “Field refers to the number of seconds after launch when MECO occurred. MECO stands for “Main Engine Cut-Off” |
| Interrelationship | Defines if there is an important interrelationship with other available data in the same structure | “User account status code and user reactivation indicator are referenced together for obtaining the correct status of the account.” |
| Values, Range, or Examples | Proves insight into the range or bounded set of values possible. | “Valid FICO scores are between 300 and 850. A FICO score less than 300 or greater than 850 is invalid. Negative numbers should never be used.” |
| Data Sourcing | Where the data comes from or how it is generated. | “This FICO score is provided by Equifax.” |
| Reference/Notes | Provides links to training documents | “For more information on satellite launch thresholds and valid values, please see https://example.org/reference/DOC-12345.” |
| Proper Grammar & Complete Sentences | Definitions should start with the term being defined. | “Currency Code is the ISO three-character code indicating the currency for the transaction.” |
| Update Frequency/Retention | Information on source application, frequency of upload, and/or retention policy, if applicable. | “Data is updated monthly for the entire customer population.” |
Not every field will require every characteristic. However, when it comes to the template presented to an API designer, we should provide examples that illustrate better, more complete information. If we give a designer a bare-bones, minimally worded OpenAPI description, they’re likely to continue that same approach in their work.
Conclusion
As your API landscape grows, perhaps versioning or better field descriptions aren’t a primary concern. However, hopefully, these examples have sparked some ideas on how you might lean in on the issues that concern you.
And it doesn’t have to end with just the templates. At the recently completed APIDays conference, ADP’s Boris Vernoff demonstrated how their customized environments promote consistency within their design environments (screens begin around the 15-minute mark). Rather than starting the design process with a blank page, a designer can select from a series of prompts. This ‘wizard’ approach does constrain the possibility space. However, in doing so, it directs energy to solve the unique business problem and away from introducing variance on non-value-adding API mechanics.
There is a lot that goes into creating APIs with greater consistency and cohesion. What is your environment doing to make that easier?
