11436 SSO

API Design: Stability Versus Readability—Must One Choose?

mnally
Jan 25, 2019

Good API design separates APIs that merely expose assets from those that help developers get things done. As I’ve written before, and as we’ll explore in this article, good design includes the style in which web API URLs are constructed.

Below are two API URLs that exemplify two divergent schools of thought on URL style. The first example is an anonymized and simplified version of a real URL and the second is a theoretical URL:

https://ebank.com/accounts/a49a9762-3790-4b4f-adbf-4577a35b1df7

https://cinemacanon.com/genre/documentary/film/los-angeles-plays-itself

Some major differences are obvious:

  • The first URL is opaque, providing enough information for a human to infer that the URL references a bank account at ebank.com, but nothing else. For those without a photographic memory, the URL details will be difficult to remember and difficult to distinguish from other, similar-looking URLs.
  • The second URL is much easier to interpret, memorize, and compare with other URLs. It tells a clear story: Los Angeles Plays Itself is a film in the documentary genre, and it is listed, along with other films in other genres, among the offerings on the fictional Cinema Canon website.

Because the second example is much friendlier to humans and because APIs are products used by human developers, it may seem that the hierarchical style is preferable. This is not always the case, however.

Conitnue reading this article on Medium.

Creating World-Class Developer Experiences