As you already know, APIs play a significantly large role in software development these days. Simply put, APIs have come a long way in the last decade. Today, creating an API from scratch is an art of its own, just like a good system architecture or designing a perfect UI.
People who design public API already know this. However, inexperienced designers that are trying to design an API that will be used internally to connect a few Microservices probably have no idea what are they getting themselves into.
In order to help you prepare yourself for the task, we’re going to go over some of the more rudimentary API design models…
1. The Command-Based Model
Like other models on the list, this one is also known by a couple of names. In most cases, you’ll hear programmers refer to it at the RPC approach. The abbreviation stands for Remote Procedure Call and it’s associated with XML protocol payloads like SOAP and XML-RPC. We should point out that this model is a bit dated and that you’ll have to deal with it in legacy system, however that doesn’t mean it’s bad.
As a matter of fact, the objective of RPC is to come up and represent remote implementation similarly as local object methods in your language of choice. In this case, the remote and local code API designs become one and the same. There are other command-based models out there – such as gRPC and JSON-RPC – but the term “RPC” is usually used interchangeably with it.
2. The RESTful Model
You’ve probably heard the term rest being thrown around when talking about APIs – there’s been much fuss around REST API docs and their importance in the last few years, for instance. This is actually an abbreviation for “REpresentational State Transfer” and it originated from Roy Fielding’s ground breaking doctor dissertation.
Since REST APIs are now pretty common, and the model revolves mainly around this principle: Try to use whatever HTTP gives without creating a layer below. Essentially, that means that you should use URLs to point to HTTP status codes, caching semantics, headers, etc. REST API response is always the serialization of a resource, usually in JSON format. However, other formats, like XML are also in use.
3. The Query-Based Model
The last model we have for you is quite similar to the first one in that it has a single-point URL. Client developer comes up with a query, which describes what information they want the server. In turn, the server will obey the command just like a developer that’s writing a query for database servers. Basically, this models moves all the power from the server to the client.
One of the most popular protocols for these models is the GraphQL. This particular protocol is all about minimalism and simplicity, which is why so many inexperienced designers use it. One of the biggest advantages of this query-based model is that the client can request all the data they need in one single request. The model is still relatively new and there’s much hype around it, partially because its origins are connected to Facebook.
Final Thoughts
Of course, there are numerous other models out there. We didn’t even talk about the Hypermedia-based model, which, some people feel is crucial for REST development. However, we feel like this article gave you a basic idea of different design models. We hope it will motivate you to do more research and approach API design as seriously as possible.