The 5 Basic API Design Paradigms
Web APIs play a very important role in today’s software development. Just like designing user interfaces or creating a great system architecture, designing APIs is a craft of its own. When running a public API program this is obvious, but even when APIs are just used internally to connect microservices or you have a proprietary mobile app talk to its backend server it won’t hurt to give this a bit of thought. Due to the importance and depth of this topic it is something that cannot be covered in a single post so we plan to regularly revisit it on this blog to share experiences and compile best practices. Consider this the first article of a series on API design. For today, we’ll start with a look at API design paradigms. I’ve identified five of them: “whatever works”, command-based (RPC), CRUD/resource-based (“RESTful”), Hypermedia-based and query-based.
The simplest and most straightforward way of approaching API design is to just do whatever works and is easiest to implement given the stack and knowledge of the developer. Using
GET for everything and mixing credentials and parameters in the URI string certainly makes it very easy to test an API in the browser and call it using
file_get_contents() in PHP. The problem with “whatever works” is that it can be very different depending on who is responsible for implementing and it encourages bad client design. There’s no consistency. APIs start to reflect the design choices and implementation specifics of the programming languages used on the respective client and server (ever seen
api.php as an entrypoint?) instead of being designed to work well in modern polyglot environments. I’d really encourage everyone who’s doing APIs (and that’s essentially every developer!) to think further than this.
RPC stands for “remote procedure call”. The RPC approach is often associated with the seemingly cumbersome XML payloads of protocols such as XML-RPC and SOAP. Those protocols seem a bit dated; you’ll often have to deal with them in legacy systems but will hardly find them in new implementations. Still, the intention behind RPC isn’t all bad; essentially the objective is to think of and represent remote implementations in the same way as local object methods in your programming language. Remote API design becomes the same as local code API design. There’s also newer standard protocols for command-based Web APIs, such as JSON-RPC, as well as highly efficient binary protocols such as gRPC. What all command-based approaches have in common is that if they use HTTP they only use it as a transport protocol that
POSTs to a single URL without being able to leverage HTTP semantics such as caching.
A term that is often used in conjunction with APIs is REST (which is short for “REpresentational State Transfer”), going as far as using REST API as a synonym for any Web API. The term and its definition have their origins in Roy Fielding’s 1994 doctoral dissertation. Most API designers probably haven’t read it. Thus, not every API that calls itself REST is actually “real” REST according to its definition. Still, there are a lot of typical practices of so-called “RESTful APIs” as a common ground to work on. These can mostly be summarized as: “Leverage whatever HTTP provides! Don’t invent another layer below.” More specifically, this means using URLs to point to resources, different HTTP verbs as CRUD instructions, headers for meta information, appropriate HTTP status codes and HTTP caching semantics. The response of a REST API call is always the serialization of a resource, typically in JSON format but others such as XML are still in use and often APIs use HTTP-native mechanisms such as the
Accept header to let clients choose one of multiple resource representations. Resource-based APIs typically use clean and easily understood verb and URL combinations, so that e.g.
GET /users returns a list of users,
GET /users/1 returns information about the user with ID 1,
PUT /users/1 would update and
DELETE /users/1 would delete the same user.
Hypermedia can be considered an extension of the basics of RESTful design. And if you asked Roy Fielding he’d tell you that you have to do Hypermedia otherwise you’re actually not doing REST. The idea is that API calls should not only return a resource but, to use the words of Mike Amundsen who gave a talk about it at REST FEST 2016, “the thing that you get back tells you what you can do next”. In an ideal world you would give the client one API resource URL and it could figure out potential actions and other related resources. Regular APIs require developers to write the logic of the program and the respective API calls into the client code, whereas Hypermedia APIs can drive this from the server side. In his talk, Mike gave examples of action buttons and forms in a client application being dynamically created. Hypermedia is still a hot topic with many discussions surrounding it and technical standards with acronyms such as HAL and HATEOAS thrown around in academics and the industry. We’ll cover them in future posts on this blog.
Query-based APIs are somewhat similar to command-based APIs in that they have a single endpoint URL. The client developer formulates a query that describes exactly what information they want from the server and the server obeys their command, similar to a developer writing an SQL query for a database server. The power is moved from server to client. A popular protocol for query-based APIs is GraphQL. In “5 Potential Benefits of Integrating GraphQL”, Kristopher Sandoval says that “GraphQL is all about simplicity”. One of the advantages of GraphQL is that clients can request data in one request that would require multiple roundtrips in another API if that API was not specifically designed for a specific use case. GraphQL is a relatively new approach with a lot of buzz surrounding it, probably partly because its origins are at Facebook. It should be noted, however, that Facebook uses GraphQL as an internal API between their server and their native mobile clients while their public “Graph API” still has a RESTful design.
I hope this first article has given you a basic idea of the different API design paradigms. We will cover these protocols and comparisons between them in further posts, so make sure you stay connected to this blog via the feed or our social media channels! If you need advice in choosing an approach towards your API strategy or want help with API design you can always hire us for consulting.