What is a REST API?

Hey, thanks for returning for part three of this series. It’s not easy to digest all this information, but you’re here and ready to learn. That’s great. In case you happened to miss the first two articles, we talked about what APIs are and how they work. In this article, we’re going to talk about a popular API design practice called “REST.”

What is REST?

Back in the Wild West days of the internet when I was cutting my teeth on HTML in the mid-1990s, everything was new and there weren’t really standard ways of doing stuff on the web. These were the days of dial-up modems and the first web browsers, Mosaic and Netscape. Anyone picking up the phone would interrupt your connection and arguments would ensue. This is also the time America Online was flooding everyone’s mailboxes with floppy discs and CD-ROMs promising thousands of hours of free online time per month.

Like any new invention, it took a while for the dust to settle and for standards to emerge. The only real standard most of us webslingers were using back then was HTML. There were no web apps at the time. There was not a single social media network. Nobody had heard of Amazon and he wasn’t rich yet. The internet was too slow to stream video and audio (unless you used RealAudio!). We walked uphill to school both ways. And we liked it!

As an excited 14-year-old, I couldn’t afford my own .com domain, so I paid to share a domain and purchased https://anthonygarone.thestud.com. How embarrassing!

Through the dot-com boom, corporations and individuals were getting on the web and usage was exploding. The world needed a way for internet-based services to communicate safely and reliably. And in the year 2000, some smarty-pants dude solved the problem by inventing REST in his PhD dissertation.

Okay, but what is REST?

REST is an acronym for REpresentational State Transfer. It defines a set of verbs and data exchange expectations for people writing web-based services and applications. Don’t let the acronym and the sound of its complexity fool you. REST is easier than it sounds.

All you really need to know from a high-level is that REST defines a set of verbs and architectural practices that make web services easier to use from a developer’s standpoint. The verbs are CREATE, DELETE, UPDATE, GET, and other words that describe how a computer on the web might handle data it’s sending or receiving. There are technical implications to each verb, like the difference between POST, PUT, and UPDATE, but we don’t really need to go there.

A REST API has endpoints (remember those from our first article?) that accept data using the verbs defined in the REST standard. For example, when you update your password on Facebook, your web browser would send an UPDATE request to their Password endpoint. In your app, you might write something like:

SendUpdatedPassword(“UPDATE”, TheNewPassword, “https://example.com/api/password”);

In this theoretical line of code, we have a function called SendUpdatedPassword() that is going to use the “UPDATE” verb to send the variable TheNewPassword to the Password API endpoint at example.com. Pretty simple and straightforward, right?

An old-school, pre-REST API call might look like:

SendUpdatedPassword(TheNewPassword, “https://example.com/api/password”);

Back when this type of code was relevant, the only verbs anyone used were GET and POST. GET allows you to download data from a web server and POST allows you to send data to a web server. The problem is that everything used those two verbs. There was no clarity between creating a password, updating a password, deleting a password, and you had to hope your code made it clear so you’d remember next time you looked at it. Furthermore, any data your app would send would use POST, which simplified things, but led to a lackadaisical attitude toward data handling.

In other words, the old web just wasn’t as secure as it is now thanks to the API and security standards we have today. Like anything else, we learn as we grow and we have matured significantly on the internet. But don’t be misled, we sure have a loooong way to go until the web is inherently secure and your data is handled properly in a universal way.

Now back to "REST"...

It would be perfectly fair of you to ask: “Why do they call it Representational State Transfer?” The “representational” part means that the data exchanged between systems is just a representation of the actual data. When you visit a website, you are downloading a copy of the website to your web browser. That download is a representation of the data that’s on the original web server.

The “state transfer” bit is a bit complicated. If you really want to know, I recommend reading this explanation.

Should you care about REST?

Skipping all the technical hubbub, there are a few signals you should pick up on when you hear “REST APIs:”

• REST is a dependable industry-accepted standard for defining how an API should work.
• Companies that offer REST APIs indicate that they follow modern practices and pride themselves as serious players.
• REST APIs are usually easier to use because they follow well-understood conventions and may also indicate easy-to-follow documentation.
• Even though REST is 20 years old, it’s “cool” to have REST APIs.

You might also be wondering if there are non-REST APIs. The answer is a clear “yes.” There are some good APIs that are not REST-based, but there are lots more bad APIs that are not. Non-REST APIs usually require more study, consideration, and fiddling, can be a sign of legacy systems that “grew organically” (into a mess), and might cause problems down the road.

It’s worth noting there are alternative standards to REST, and that gets a little complicated. If you’re really interested, check out this article.

REST vs. RESTful

Thanks to a helpful commenter, it was pointed out that I was confusing REST and RESTful in an earlier draft of this article. He was correct. Here's a helpful article that illustrates the differences: https://u6188448.ct.sendgrid.net.

Going Further

There’s still tons more to talk about to get you ready for some basic conversations about APIs. So, stay tuned.

Can we help you with clear, technical content?

Writing easy-to-understand technical content is difficult work. If you or your brand are looking to become a thought leader, you should consider hiring expert content creators like Edify Content to help you. We can generate ideas, create and manage a content calendar, get newsletters out to your followers--heck, we’ll even do it all for you! Just reach out to [email protected] to learn more.