Objects at REST, Part 1: What Is It?

Published in

The RESTful Web

11 min readMar 7, 2016

Okay, so, it’s 2016 and you don’t know what REST is, what an API is, or how to design an API with this magical thing called REST that everyone keeps talking about. You’re frustrated by the phrase “Just Use REST,” because when you go to find resources on the topic, they’re hard to discover if you don’t know what to search on Google.

I’ll start this off with a short story. I graduated from university and somehow still had no idea what an API was. It wasn’t because I was lazy and never learned it, but more so the fact that it’s not really something that was talked about often at school. Then, I went looking for jobs, and all of the postings started talking about Web APIs, REST, and that I should have an understanding of it.

Turns out, this is a foundational concept that many jobs in tech require their staff to understand now. So why did I never learn it in school? I don’t really know (I really don’t have an answer, but it seems Comp Sci programs struggle to keep up with the latest tech like boot camps do), but needless to say I set out to learn all about RESTful APIs. I now want to pass that knowledge on to anyone who finds themselves in a similar situation.

I graduated from university and somehow still had no idea what an API was.

The goal, ultimately, of this mini-guide is to help you get up to speed with an industry best practice that you should know.

What This Guide Is Not:

A fully fledged, granular guide on REST and APIs. That would just require so much detail, and probably not the most suited to a series of Medium articles.

What This Guide Is:

A get-up-to-speed guide on REST and APIs…the “essentials,” if you will, to modern API design in 2016. I will explain a lot of details, and if you want to learn more, I will provide my sources for what I would approve as excellent next steps in the RESTful API learning process.

Structure of the Article:

Glossary of Terms
What is an API, and what is REST?
Common Conventions / RESTful Principles
REST Interface Constraints
Summary So Far

Glossary of Terms

Before we really get started, I want to supply you with a few key terms I’ll be using in the rest of the article. This will help you understand what I mean when I mention certain concepts.

Hypermedia: As described by Wikipedia, Hypermedia “is a nonlinear medium of information which includes graphics, audio, video, plain text and hyperlinks.”
Resource: In RESTful APIs, resources are identifiers to any piece of interesting information the server can provide. For example, a resource could be the users of a system, a user’s timeline of posts, or a blog post, like this one. A practical example is twitter.com/Stuart_Weir, where my name is the identifier of a user resource in Twitter’s servers.
URI / URL: URI stands for Uniform Resource Identifier, which is simply a set of characters that is used to identify a resource. As we saw above, twitter.com/Stuart_Weir is a resource, but this resource is identified by a URI. A URL, or Uniform Resource Locator, is the most commonly used version of a URI, and is often called a web address. The whole of twitter.com/Stuart_Weir is the URL.
State: this is a pretty straight-forward term, but quite simply, it’s used to explain the current “state” or “context” of an application. In RESTful APIs, Hypermedia (see #1) is used as the engine of application state.
Media Types and Content-Type: A Media Type is the specified data format that will be sent in the Request / Response of a client-server exchange. A Content-Type is the HTTP Header field used to specify the Media Type. For example, Content-Type: application/json would be in the HTTP Header field, that specifies a Media Type of application/json.
Request / Response: A Request / Response is an interaction between the client and the server. The client will send a request to the server to do something, or get some data, and will wait for a response from the server on the status of that request, along with any extra data pertaining to that request.

To sum all this up, let’s quickly use all these terms in an example. A client (my web browser), sends a request to the URL www.twitter.com, specifying a Media Type in the HTTP Header field, “Content-Type.” Twitter responds to my request with an HTTP status specifying that everything went okay, and the data my browser requested (the web page). From this web page, I have a few options. I can post a new tweet, I can go to my profile, etc. Let’s say I want to go to my profile page. I click on my profile, and this sends another request from my browser (the client) to the server with the Hypermedia link www.twitter.com/Stuart_Weir. Notice that my request was for twitter.com, with the /Stuart_Weir resource appended. Twitter’s server sees that “yes, I have this resource,” and sends it back to my web browser, where I see my profile page.

For a more full-fledged glossary of API terminology, I highly recommend taking a look at Mashape’s API Glossary. This is an incredibly useful resource for reference, and created by what I like to call the “King Kong of APIs,” Mashape.

Now that we have a bit of foundation laid out in terms of terminology, let’s get to the heart of this article.

What is an API, and what is REST?

An API is an Application Programming Interface. This sounds super technical, but it actually really isn’t. It’s essentially an interface for programmers, much like a User Interface (UI) is an interface for product users.

To give a quick example, when someone directs their browser to twitter.com, it takes them to a UI that allows them to do a few things. Twitter will ask them to log in or sign up, and from there the UI will change/update so that the user can do even more things with the service.

Much like the Twitter example, APIs are essentially a more technical version of this. RESTful APIs expose resources (see above) that a programmer can interact with. APIs (and RESTful APIs more specifically) should be easy to use and easy to discover. In other words, like when a user goes to Twitter, the user should understand how to use Twitter, and discover different features of Twitter easily. In the same way, great RESTful APIs allow programmers to easily use their features, and discover the API quickly.

REpresentational State Transfer (REST) offers a way to structure APIs and offers certain opinions and conventions that make building APIs easier, more efficient, and standard, so that a client user (a programmer wishing to use that API), can quickly get up to speed with the API simply by understanding it follows certain conventions. REST was first introduced in Roy Fielding’s dissertation, Architectural Styles and the Design of Network-based Software Architectures. For a full overview of REST as fielding defined it, please check it out here.

REST is a stateless, client-server architecture that offers a cache-able protocol, and it’s almost always implemented via HTTP. It typically uses HTTP methods for Create, Read, Update, and Delete (CRUD) operations, and as such, is standards based. We’ll get into the definition of some more of this terminology later. REST is also language independent, meaning it can be implemented in numerous programming languages, so a REST API server built in Ruby, for example, can be consumed by a Go(lang) client. If we’re to follow with this Ruby and Go example, you may be wondering, “how does data written with Ruby code transfer to data that Go can understand?” Good question, but I’ll get to that in a later post.

Okay, so what else is there to know about REST? For now, let’s quickly sum up what we just learned about APIs and REST. An API is an Application Programming Interface, which is essentially software that exposes some functionality that other software can consume. In RESTful APIs, this is built off of a client-server architecture that we’ll take a look at in more detail in a moment. REST allows for us to transfer the representational state of a resource from the client to the server, and vice versa. Moving on.

RESTful Principles:

REST comes with a common set of conventions and principles in order to architect powerful, flexible, and scalable APIs. For example, one common convention with REST is that when handling a URL’s method (GET, PUT, POST, DELETE, etc), we use nouns instead of verbs for the resource name. This means that www.example.com/getusers would be www.example.com/users, and that will GET the users resource. Here are some more:

Client-server architecture: this is to help separate concerns, as managing state between a client and server would become exhausting, not only for a programmer, but exhausting on the system as a whole. In the example above, the Ruby API was the server, and there was a Go client.
Communication should be stateless: the interaction between the client and the server should be without state, meaning each request from the client to the server is a self-contained interaction, that does not require context from previous requests. However, both the client and server can hold their own state.
Cache-able: being able to cache a response from a server can greatly speed up interactions, in some cases, completely eliminating them.
Uniform interfaces between components: this is a distinguishing feature of REST, where the independent evolution of components is encouraged. This is because the actual implementation of the components (the code) and the services (what that code provides) are decoupled. In the Ruby and Go example, the two components were the Ruby RESTful API and the Go client, whereby the implementation of the Ruby code is unimportant to the Go client, as long as the Go client receives the Media Type it expected to receive, among others.

REST Interface Constraints:

Okay, so we now know some of the core principles behind what makes RESTful APIs RESTful, but what constraints do we need to implement on our RESTful APIs? Here are the main four:

Identification of Resources: One of REST’s key abstractions is a resource. These are identified in requests, such as www.example.com/users, where the resource in this case is users. This is conceptually separate from representation of the response, which could be a Media Type specified by text/html or application/json, for example. More explanation in #2.
Manipulation of Resources Through Representations: A representation can indicate the current or desired state of a requested resource, as well as other forms such as error conditions for a response. The data format of a representation is known as a media type, as explained above in the glossary section. If a client holds a representation of a resource, such as a representation of all the users, it has enough information to modify or delete this resource. So, if a request for the resource users is sent from our Go client to the Ruby API, a representation of that resource could be the response. Once the Go client has a representation of that resource, it might execute a DELETE request on all the users, or a single user resource if it has the authorization to do so. Be careful not to confuse a resource from it’s representation. Think of it as a box filled with old toys you had as a kid: The box has a name written on it, “old toys,” and inside the box is the representation (the toys) of that resource (the “old toys” box). This isn’t entirely accurate, but hopefully it helps paint an image in your head.
Self-Descriptive Messages: A message should contain enough information to describe how to process it. For example, if the response to a GET request is JSON, the Media Type should be specified as application/json in order for the response to be properly processed. There are a few things going on here. In the GET request, the request specifies that the HTTP method is GET, and the Media Type is application/json. So, inside this message, it’s self-descriptive because it specifies what to do with the data it’s requesting. This is why the message is also referred to as stateless or context-free; the message requires nothing outside the scope of itself to be processed.
Hypermedia as the Engine of Application State (HATEOAS): This is a fancy way of stating that what actions are available to the client vary as the state of the resource varies. In RESTful APIs, we use Hypermedia as the way we move state around. Hypermedia often is a link to another resource, however it can also be audio, video, graphics, or plain text. As described in this article, “a RESTful application enables the server to inform the client of the possible ways to change the state of the application via hypermedia.” To use the Twitter example again, say a user navigates to twitter.com. The user has two options: log in or create an account. These are both controlled by hypermedia links, which are used as the engine of application state. Say the user doesn’t have an account. They fill in their details, and hit “Submit.” A POST request is sent by their browser to the server, which then changes the application state of Twitter (to one where the user is now logged in). This is an example of using HATEOAS.

To sum up some of the concepts of REST covered so far, here’s what Raphael Simon, one of creators of goa had to say about REST:

REST services expose state through resources (state can be data in a database for example). Each resource represents an abstraction that usually maps to a model in the backend (a “customer”, a “product”, etc). It doesn’t have to be a one to one though, for example relationships may be exposed as resources as well or may be hidden from the API depending on what the service needs enabled. Resources are managed by making requests to the service that exposes them. In HTTP REST establishes the following mapping:
* POST to the collection of resources to create a new resource
* PUT/PATCH to an element in the collection to update it. “Usually” PUT is used for full updates while PATCH is used for partial updates.
* GET to the collection returns all resources
* GET to an element of the collection returns that element
* DELETE to an element of the collection deletes that element
From a strict REST point of view, this is pretty much it. In reality APIs tend to expose additional actions on resources. REST dictates that these should be represented as resources. For example if a service exposes a “vehicle” resource and the intent is to allow the API user to start the vehicle, REST would dictate that a “started_vehicle” resource be introduced for example. Creating that resource would return a started vehicle. Sometimes though that is unpractical (typically actions that tend to update state like the example here). In these cases resources define additional actions typically located under the resource location.

To Sum Up What We’ve Covered…

I covered a lot of content in this post, so feel free to go back, read it (or parts of it) again. It’s okay to not fully understand what’s going on yet. However, what we’ve covered so far is this:

Application Programming Interfaces (APIs) are like User Interfaces (UI) but for programmers. They should be designed to be easy to use and discover, much like UIs.
REST stands for REpresentational State Transfer. It was initially proposed by Roy Fielding, and provides a set of conventions that standardizes the creation of uniform interfaces in APIs.
REST is based on a client-server architecture, is stateless, and is preferably cache-able. Most often it is implemented via HTTP as to use HTTP’s methods for CRUD operations.
REST’s API constraints include the identification of resources, the manipulation of resources through representations, should have self-descriptive messages, and Hypermedia is the Engine of Application State, meaning that the actions that are available to the client is based off the state of that resource.

What’s Next?

Next up we’re going to take a look at some main considerations that go into designing a RESTful API, building off of our current working knowledge so far. Then, in the third and last article, we’ll put it all together by implementing that design in code.

Stay tuned for more in the coming weeks!

Sources: