Definitive Overview of RESTful APIs

This blog post has been inspired by years of documenting APIs, working with APIs, and hearing people say things like:

  • “Wait, what exactly is an API?”
  • “What does REST really mean?”
  • “Wait, but isn’t everything on the Internet RESTful?”
  • “Well, everything on your computer is an API.”

Okay, the confusion stops now. Seriously, I can’t even handle this anymore.

Disclaimer: I’m trying to help, so please bear with me. This is an ongoing process, and I don’t know everything there is to know about RESTful APIs. If anything in this post seems confusing, unclear or just plain wrong, please email me ASAP so I can help further alleviate the confusion!

What is an API?

Let’s just start by clarifying a very important term:

Web API:

An interface to a server somewhere that allows you communicate with said server via the World Wide Web. That is, via HTTP requests, or via AJAX requests (that’s XMLHttpRequests, also known as HTTP requests sent from within a web page).

The term API can technically be applied to almost any programming language or interface that is used by other programs. But using the term API in this way is first off, totally useless. And second, really confusing.

So for the record, this post is about Web APIs, not any other kind of API. But I will refer to Web APIs just by the term API throughout.

What is a REST API?

Now let’s quickly start with what it isn’t:


An SDK is a library or language that can be used for implementing some piece of software in your own code. Android, for example, has an SDK that you can use to develop Android apps. Here’s where things get a bit confusing. An SDK can utilize an API. In fact, an SDK might be designed for the sole purpose of using one particular API. Google, for example, has an SDK that allows you to utilize the Google Maps API with JavaScript code. The SDK and the API are two different things. Let me be clear, you are using the SDK to write JavaScript code that is accessing the API.

Confused yet?

Let’s get to the meatiest question of all:

What is REST?

REST is not a technology.

REST is a concept.

REST is a philosophy of software architecture.

You could argue ’til the cows come home about whether any particular piece of architecture is “truly RESTful” (trust me, I’ve done this — it is generally not worth it). In the same way, you might argue about whether a framework is “truly MVC” or a company follows a “truly Agile” development process.

These are philosophies that you can approach, but it’s pretty hard to even imagine the platonic ideal existing in the real world. Don’t worry too much about it. It’s probably not worth arguing the semantics too much, or you might lose your hair or your friends over it.

Let’s get into the official definition on RESTful architecture.

Six Constraints

The 6 constraints are the rules that a RESTful application is supposed to adhere to. Technically, the application has to meet the first 5 to be considered RESTful. But see my note above regarding semantics and arguments.

I will do my best to sum these up for you here:

  • Client-Server Separation: The client and the server are two separate entities. They are only connected while data is being sent between them. Data is only sent in the form of a request or response. There isn’t just data streaming between the client and the server all the time. This would not be RESTful.
  • Stateless: This is one of the most complicated simple concepts of all time. Put simply, each action should be autonomous, and complete. All information required to complete the transaction is sent in one request. HTTP is stateless in this way. You send an HTTP request, you get one response containing all the information you asked for.
  • Cacheable: A sort of workaround to the ‘stateless’ piece is for the client or the server to store information in its own cache. This is not the same as being stateful. When a request is sent, the client has to tell the server if it already has the site cached (and vice versa). The server doesn’t know anything about the client other than what the client tells it in a request.
  • Uniform Interface: Your API needs to have a consistent interface — honestly, just for everyone’s sanity, I think. It doesn’t necessarily matter exactly how you choose to implement your API endpoints — using query strings, URIs, parameters, or some combination thereof. But whatever you do, be consistent with it. Don’t have a POST to one object take a body, and a POST to another take a query string. Don’t have multiple endpoints for the same resource. There should be one interface for each action. Your endpoints shouldn’t move around.
  • Layered System: This gets to why the Internet is often used for RESTful APIs. The Internet is already driven by a layered model. This is important, because it makes it possible to add security, authentication, and other features either on top of or below the API layer. This allows RESTful APIs to be versatile and extensible.
  • (optional) Code on Demand: I don’t really think this one is used a lot, because APIs typically send JSON or XML. And it’s “optional” (as in, not required for an API to be RESTful). The basic idea is that you can send executable code, such as JavaScript, to the client when requested. Again, I don’t know if I’ve really seen this… if anyone knows of any examples, do let me know! (I’ve always been curious about this mysterious last constraint…)

And that’s about it! Simple, right? No?

Well, here’s the TLDR:

The core concept in REST, if you remember nothing else, is that it involves Resource Representations. Put simply, each resource has some location on the server. You communicate via representations of that resource (for example, a JSON file with configuration data). These representations are then interpreted by the server to perform CRUD (create/read/update/delete) actions.

Example Time!

After all that discussion, maybe you would like an example? Sure, why not!

Here is a set of API endpoints that might be used to send HTTP requests to a RESTful API on a server:

Retrieve a list of all favorite things on the server/DB

Create a new thing to add to favorite things (this may or may not override all other things in the list, depending on API design)

Add to the list of favorite things

Delete the entire list of favorite things

Get item 123 from the list of favorite things

Remove item 123 from the list of favorite things

And that’s it. Seriously. That’s a RESTful API. (okay, well it’s missing a few things, like actually existing for one, but I think you get the picture?)

What Other Kind of API is There Even?

You may be reading this and wondering, why would anyone do this in any other way? You took a long time to explain something pretty simple — it’s just HTTP!

There are actually numerous alternatives to REST, some outdated, some still in use. The key difference is that REST is basically language-agnostic. You can use it with XML, JSON, you could just send raw HTML, it doesn’t matter very much, as long as you’re following the 5–6 constraints mentioned above (or, you know, mostly following them) You don’t even need to be using HTTP, it’s just very handy, since we’re mostly using HTTP for so many other things these days, and since it adheres to the RESTful architecture so readily.

For completeness, here is a list of alternatives to RESTful APIs, most of which require language or technology restrictions:

  • SOAP
  • URL encoded forms
  • Java SE 7 Remote Method Invocation (RMI)-related APIs
  • Distributed Component Object Model
  • Common Object Request Broker Architecture (CORBA)
  • and I’m sure many more…

— — —

Wow! Thanks so much for reading all the way to the end. Hope this wasn’t too heinously boring, and maybe a little informative even?

Please feel free to leave comments, or send me an email!


Originally published at

Show your support

Clapping shows how much you appreciated Alexandra Polubiec’s story.