RESTful APIs: a Marriage (of metaphors)

APIs are more than just vaults of info you can pillage for your own apps (and let the count of all metaphors in this article begin with that sentence: metaphor 1). They are sometimes vaults of data, but saying an API is just a data source you can pull info from is like saying your Lamborghini is just a roof for your driveway (that's metaphor 2 because, yes, I'm counting similes as metaphors. I'm allowed to do that because
a) I taught English for a long time, and
b) I thought about writing "is akin to" instead of "is like" but that sounded too pompous. So, take that: metaphor 2).

API actually stands for "Application Program Interface," which sounds like a name for the way people have sex in Demolition Man (metaphor 3). But it actually means something much less weird and creepy. It indicates that there's a piece of software, and it has a way of talking to other software. In API terms, we call this a "contract" between the two pieces of software.

Lots of different kinds of software have contracts. Stuff you'd expect, like servers, but also things you wouldn't think about like the (totally unnecessary) tech in super fancy refrigerators, and the not-at-all-obtrusive little device I just plugged into my car today (for real) that apparently measures my speed and braking and etc to report back to my new car insurance company to tell them how good of a driver I am...which I'm not at all weirded out about. And obviously find totally normal. Obviously.

Anyway, these contracts between pieces of software include prewritten and well-structured protocols for requests and responses. So when one piece of software sends a request--in the correct and appropriate format, as prescribed by the contract--the other piece of software is expected to send a response in the appropriate and prescribed format that both pieces of software agreed to in advance. Which is what leads to our real whopper of a metaphor: APIs are just like marriages (meta-four).

It's like when you marry a guy, and sign a marriage contract, now he is like obligated to respond to all your requests with a well-formatted and appropriate "As you wish." Or if he doesn't understand what a transcendental film The Princess Bride is, he might just say "yes ma'am and/or sir."

With APIs, there are a lot of rules about how to format these requests/responses. Back in 2000, a dude named Roy Fielding wrote his dissertation on APIs (among other things) and pretty much set the rules of APIs in stone, a-la-Moses and the Ten Commandments (metaphor 5). He called these RESTful APIs (RESTful stands for REpresentational State Transfer). There's a lot of debate about what exactly the rules mean, which ones are mandatory and which ones are more like "don't jaywalk" rules (metaphor 6), and as technology changes, of course the rules around it change, but here's a two-cent break down of some of the currently most widely accepted rules about what your API has to do/not do in order to be considered a RESTful API:

1. Separate concerns between the front-end and the back-end. This just means keep your front-end UI business separate from your data storage, which will make your UI way more portable between different platforms. You can think of it as a mullet with "business in the front, party in the back," (metaphor 6) since of course the back-end is all-party-all-day for devs, while the front-end has gotta look professional and whatever for, ya know, the actual living, breathing people who will use the application.

2. Keep your back-end stateless. Every time the client sends a request to the server, that client damn well better give the server all the information necessary to understand the request, and absolutely cannot use any of the stored context on the server. This is because servers are selfish and greedy and proprietary. Just like Apple...(metaphor 7). Actually it's cause you wanna keep your server as lightweight as possible and because a server's job is to deal with data, not a client's current specs.

3. Just tell your client up front if you're going to cache their data or not. No need to be coy, Ms. Server. Just tell the client whether or not the data you're sending back to the request is cacheable.

4. But the whole API can be layered, which means the server can be a little bit coy. In other words, the server can take the request from the client, and then make a few requests of its own, to other APIs, and there can be a whole lot of other interactions the server is doing behind the client's back, before it finally returns a pristine, shiny new response to the client, all without the client knowing anything about the server's goings-on. In light of my previous metaphor about this being a marriage, I think this might now mean that servers are allowed to "layer" their marriage, by which I mean cheat on their spouse a whole lot (metaphor 8). Shame on you servers, shame.

5. Finally, RESTful APIs have a "uniform interface," which is kinda complicated but think of it mostly as meaning that all requests need to have the same sort of info and style every time, and the back end should never return any part of its schema (eg organization) in the responses it gives back. Also, if the server wants to be a real peach, it can include self-descriptive messages in its response.

That's about it for the super-mondo important rules of RESTful APIs. Follow those, and you'll have the API of your RESTful dreams. For now. Though it seems the day is coming when RESTful APIs might finally feel their marriage disintegrating, as they grow apart and realize they have different interests now (like GraphQL) and just really can't make it work anymore (metaphor 9). But until then, live it up you dirty, cheating servers, and keep the party alive.