Consistent API designs make people feel outrageously smart
API governance aims to help people maximize the value generated by APIs by fostering the creation of the right APIs in “the right way.” One of the essential dimensions of creating APIs “the right way” is designing consistent APIs.
Consistency, in general, means presenting features that are in harmony with one another or a whole. It’s a concern for the design of anything: a kitchen appliance, an elevator, a website, or an API. Consistency matters for the design of any API—whether it’s a public, partner, or private API. It’s a concern in each API and across APIs.
But what exactly is the difference between an inconsistent and consistent API design? And what are the consequences of designing inconsistent or consistent APIs?
What is an inconsistent or consistent API design?
An inconsistently designed API will show variations within itself and with other APIs. For example, It may manipulate a single business concept, “contract,” modeled unnecessarily differently from operation to operation. It may be randomly named “contract” or “document,” or may be identified by an integer reference or a string documentCode, or may not contain the same properties. And inconsistencies may concern more general topics; not finding a contract may result in a 404 Not Found error, while not finding a customer may be signified with a 400 Bad Request. Also, date property types can be randomly chosen between Unix timestamp or ISO 8601 date. And such inconsistencies can also be visible across APIs. Different APIs manipulating this “contract” business concept may have various ways of naming and identifying it. Different APIs may also have different error message structures, propose different flows when a use case involves uploading a file, or use too various security mechanisms.
A consistent API will be consistent within itself and with other APIs. Operations within and across APIs share similar looks, behaviors, and even more precise elements like data models or properties. A 404 Not Found will always be returned when an element is not found. Any error feedback will leverage a standard data structure. Standard pagination features will be present in all search operations. Any flow involving uploading a file will be the same. Any business concept will hold an “id” property that identifies it. All dates will be in ISO 8601 format and only use time precision when needed. All APIs will rely on similar, if not identical, security mechanisms. And a “contract” will always be a “contract” identified by an “id” of type string across all APIs (when that makes sense from a subject-matter perspective).
What are the consequences of an inconsistent or consistent API design?
If APIs are inconsistent, developers will need more time to figure out what to do and write more code to mitigate the differences in data, formats, error feedback, or security measures. And constantly writing unnecessary specific code augments the risk of bugs. Also, they will ask more questions and need extended support.
If APIs are consistent—sharing a familiar look and behavior—anyone who has learned how to use one will be able to use another instantly. And if those APIs look like any other outside-world API, that reduces the first learning steps even more. Their consistent design allows developers to reuse client code between different APIs, and combining them will be simplified if those APIs rely on consistent data. If developers don’t have to write specific code to transform data between API calls or interpret the dozens of error feedback structures, they will develop faster with fewer bugs.
Win people over with consistent APIs
And even more important, developers can guess how consistently designed APIs work. That not only reduces the time-to-value, but it also makes them feel brilliant. Such a feeling has no price, especially when the API is a public one they can choose to use or not to use.
What do you think about this topic? Tell us in a comment below.