I love APIs!
I love them! What can I do? They’re awesome! They are REALLY awesome!!!
Well, let me elaborate a bit more about the subject so I don’t sound like a 8-year-old in a Toys-R-Us store…
What is it, who uses them and why?
For those who don’t work in the IT industry, this will be a technical article, maybe it does not interest you. But if it does, an API (Application Programmable Interface) is a piece of software that usually exposes part, or parts of a system. That’s done to facilitate other companies or individuals to create their own applications using the information exposed by the API.
A good example would be the Irish Rail API. The Irish Rail has a fairly good API - although, as I say that, by the time of this writing their API is STILL like it was the first time I saw it, two and a half years ago: a few SOAP based endpoints… but they do their job of giving accurate and up-to-date information about train stations AND train schedules!
One could use that information to create a mobile app that, for instance, based on your current geolocation, tells you the nearest station and the next two to five trains going out of that station to another station of your choosing, which you could do on a drop-down or auto-complete box etc. It would be a very small, straight-to-the-point, useful app to have on your phone if you commute by train in Ireland, or if you’re just visiting the country and prefer to travel by train.
Once you have access to the data, the possibilities are only limited by your imagination.
APIs these days are everywhere. From your local supermarket to the airline companies, cryptocurrency feeds, home brokers… big and small companies use them as they are easy to maintain, without having to change anything on your app front-end (the part the users interact with, a.k.a. User Interface, or UI). You can move your entire API into a new version, add new endpoints, modify some others, add information… as long as the differences between one “payload” and the other - the data being sent by the server in response to a client request - still has the information the UI is trying to show.
Usually in cases where the payload “schema” (the structure of the data) changes completely, a new version of the API is released, and the old one remains active for a period, until all apps using this API’s old version can migrate to the new one. In case of big companies, like Google, AWS, DigitalOcean etc. they send the information to their users quite some time in advance in order to allow everyone to change their apps to use the new, improved versions.
It’s a great way to segregate your app between the code that is running in the UI and all the “critical” stuff that runs on the back-end, like accessing data, authentication and authorization, running proprietary business logic etc. You don’t want the Internet having DIRECT access to your production database, do you?
How does it work (usually)?
Talking specifically about WEB APIs (APIs running on a web server), an API usually responds to HTTP requests. The apps make HTTP requests to the web server, the server checks if there’s any program listening on that particular address and, if there is, relay the request to that program. The program then can take that request with all the information it contains (headers, body content and method - again, USUALLY), process it according to the endpoint (the URL) requested and send back a response. It’s the very well-known triad of “request-process-response” of ANY web server, by the way.
Why do I keep highlighting the word “usually”? Well… because this is not the only way of making APIs.
Like I said in the beginning, an API is a piece of software that exposes part, or parts of a system, and it does that by being executed on a computer, which allows it to listen to requests to give back responses. But that entire process can be achieved in a variety of ways, one of the most common (or usual) ones being an HTTP server.
But in fact the term API started to take form in the 1940’s and 50’s, and clearly we didn’t have Internet back then (packet-switching between two computers started in the 1960’s, by the way)! APIs where more like interfaces between computers, then it was transformed to become interfaces between computer programs. Therefore there’s more than ONE way to create and use APIs!
The “new” proposals for APIs
Request-response APIs are still the de-facto standard for building APIs and API Gateways (normally part of micro-service architectures). But there are other ways to build “a piece of software that exposes parts of a system”, right?
Well, of course! Some big companies, like Salesforce, for instance, are already using them! Salesforce not only have the “standard” APIs, but they also have a GraphQL URL and the news are that they’re building their library of Pub/Sub APIs as well! The argument is that the Pub/Sub design pattern is more reliable than a request/response because it really decouples client from server.
You see, in a request/response pattern, if the request suffers a connection issue, say network instability, for example, the request packet might get lost. You would have to make a new request. The server will never get that lost request.
From the client’s perspective, if the request gets to the server, but the server never responds, because of a bug in the API code, or network issues, your request can get stuck for a very long time on the client… maybe even forcing the client to have to close the page or restart the mobile app.
In a pub/sub pattern, though, the client sends a message and… that’s it! It does NOT wait for a response, that response can be sent 10 minutes later and it would be all fine.
Message to API developers: for the sake of our sanity (the API users), PLEASE don’t let us waiting 10 minutes for a response, that was just an example…
My point, and the argument for this pattern, is that in a pub/sub API, the client sends a message to the server; if the server is unavailable, the message is QUEUED on the client to be sent when the connection is re-established. The server then gets the message, process it as it would usually do on any other API and then sends back a message. Again, if the connection is faulty, the message is queued and sent back when possible, which makes this system INCREDIBLY reliable.
The counter-argument, obviously, is that it’s also more difficult to implement a pub/sub API than a simple request/response one (which, by the way, is something I’ll try to do live on my Twitch channel, just to see HOW difficult it really is…)
There’s also the Websocket API, which I already implemented a few years ago as a proof-of-concept, using the same Irish Rail API as a base. The technique is very simple: instead of a request/response server in place, you put a Websockets server instead. The communication between client and server is in real-time and the scheme is very similar to a pub/sub pattern, but without the queue.
Conclusion
Every pattern has its pros and cons, and we as developers have to try to find a good balance between what’s fun to play with and what’s actually best for the systems we build. I always advocate for the use of the correct tool for the correct job, independently of my personal preferences. I often find myself inclined to use HTML, SCSS and JS for everything (including mobile apps, using PhoneGap…).
Let me know, please, what’s your opinion. Did you know about pub/sub APIs? Have you used them in your projects? What do you think about these other options?
YouTube video
See you all on the next one!
