Leonard Richardson gave a talk back in 2016 called The Magic Arrow. He shared his experiences building a mobile application for the New York Public Library that allowed the patrons to borrow and read ebooks. He found there were characteristics of architectural designs that made them more extensible and reusable, and he summed them up under the idea of the magic arrow. When we draw architectural diagrams, we draw boxes and connect them with arrows.
What if we could combine the power of HTTP with the universal qualities of URLS to create a way to build an API that works like code? It would be a way to turn the web into a programming language of sorts, to treat an API as if it were code. To explain this weird idea, we’ll think about it in terms of calling functions with HTTP calls similar to how you’d call functions in code.
When we design an API—among many things—we’re designing how we think the API will change. We often reach for versioning to handle this, but versioning is a small part of the change discussion. For instance, will the versions be for the entire API or for individual resources? Will we support each version forever, or will we deprecate and sunset all or parts of versions? And at what point do we switch to a new version?