REST vs. RPC and a mention of HATEOS

This is a modified and expanded version of an email I sent a few days ago, here for public consumption.

So RPC is great, right? I need to do X to my data so I’ll just make an endpoint called /doX and hit it and bam the API did X! It’s just so simple! Except that it is the same as saying that you will only ever want to do X with your data. The only way to create a full featured RPC api is to be omniscient. RPC APIs are like saying: “These are the only things that you can do to this data, and nothing else. Only these things.”

REST APIs describe the data itself. They aren’t about you can do X with the data. If you want to do X to the data then you do X and then send it to the API for persistence. REST is a persistence layer for data rather then an API for doing things to the data. If you have seen The Lego Movie then you can think of REST APIs as the master builder API. While RPC is the “awesome” API (The Instruction booklet or maybe even kraggle…). If you haven’t seen the Lego Movie… go watch it!

REST says “hey! here are the building blocks, build stuff with them!” instead of “here is what you can build with these building blocks”. This flexibility is the key to future development. It allows you to build a system that provides flexibility for doing things with the data that you haven’t anticipated.

HATEOS is REST on steroids (some people will tell you there is no REST without HATEOS... I disagree. They have different acronyms. HATEOS is a superset of REST that maybe doesn’t always make sense). But it shares with REST the idea that it is a persistence layer and not a series of function calls over http (or whatever protocol you use).

The beauty of a good RESTful API is that it doesn’t tell you what you can build. Need to send an email? POST it to the /email end point. Want to view an email that is in the queue or one you sent earlier? GET it from /email/this-email-id-thing. No need for a /sendEmail RPC style endpoint. Because like all queues, we are just talking about a collection of objects, or an array.

Hopefully this helps make things clearer... The benefit to you is lower maintenance costs because of the simplicity of the system. Your users will get flexibility to build awesome stuff that creatively uses your data. Yes it puts a larger burden on the individual consuming applications, but that is a minor cost and one that is well worth it.

If you enjoyed this article please share it! Also, I have a newsletter that you might enjoy as well. Thanks! -Daniel