Continuous API Management, 2nd Edition

Chapter 6. API Styles

Design depends largely on constraints.

Charles Eames

APIs are a necessary design element in any infrastructure that interconnects components digitally. APIs allow various components to communicate, and looking at it this way shows what general pattern APIs actually are. When we say “pattern” here, we refer to the general communication interactions that APIs support. Note that this is at a higher abstraction level than specific technologies that define concrete ways of implementing patterns.

Since APIs are such a general pattern, the question arises whether there is one right way to design APIs. But unsurprisingly, the world is a little bit more complicated.

A good example is the “REST versus GraphQL” debate, which has been happening for several years in various forms. If we look past the strange debate that one API approach is generally better than another, it doesn’t take long to see that this question compares things on a different level. Let’s briefly look at these levels because they give us a great way to distinguish patterns (which we call API styles) from technologies.

REST is a pattern, meaning that there is no “REST technology” or “REST protocol.” HTTP is a useful foundation for implementing that pattern, but it also takes media types (the web’s term for the payloads being exchanged via APIs) to end up with a RESTful architecture that can be implemented.

On the other hand, GraphQL is a technology that defines how clients can query into a data model ...