The Basics of REST and RESTful API Development

By Jake Rocheleau. in Coding. Updated on June 7, 2016.

Web developers are frequently talking about REST principles and RESTful data architecture, as it’s a crucial aspect of modern development, but sometimes it can be incredibly confusing. REST is not a technology in itself, but rather a method of creating APIs with certain organizational principles. These principles are to guide developers, and create a more universal environment for processing API requests.

In this post, I’d like to explain RESTful development practices from a bird’s-eye view. I want to tackle the what rather than the how. Although I’ll be touching on both areas, this post is made for anyone who’s into web development, but simply cannot grasp the concept of REST APIs.

REST For Web Developers

The acronym REST stands for Representational State Transfer. This may sound somewhat confusing, and the wiki entry makes it sound even more confusing. But it is possible to simplify the terminology.

REST is just a series of guidelines and architectural styles used for data transmission. It’s commonly applied to web applications, but can pass data to software as well.

The acronym API stands for Application Programming Interface, which are methods of connecting with other libraries or applications. Windows has multiple APIs, and Twitter has a web API as well, although they perform different tasks with different goals.

Combining it all together, RESTful APIs are APIs that follow the REST architecture.

What exactly is the REST architecture?

This is where it’s tough to lay down specifics. However there are some architectural constants, such as:

Consistency across the entire API
Stateless existence, i.e. no server-side sessions
Use of HTTP status codes where appropriate
Use of URL endpoints with a logical hierarchy
Versioning in the URL rather than in HTTP headers

There aren’t any overly specific guidelines like the W3C HTML5 spec which could lead to confusion, and a miasma of uncertainty around REST terminology.

Also, the above list shouldn’t be considered hard-and-fast rules, even though they are true of most modern RESTful APIs.

restful api diagram preview — IMAGE: restful-api-design.readthedocs.io

REST is a lightweight methodology which makes it perfect for HTTP data. This is why REST became so popular on the web, and why it’s widely regarded as the best choice for API development.

As Vinay Sahni puts it, “an API is a developer’s UI.” Everything should be easy to use, and provide a great user experience. RESTful APIs aim to do just that.

Key Takeaways For RESTful APIs

These tips are in the context of APIs strictly for web applications. This means that HTTP is a requirement, and it often means that the API data is hosted on an external server. Let’s examine how RESTful APIs work on the side of the API user.

The API user is the web developer who can build a script that connects into an external API server, then the necessary data is passed over HTTP. The developer can then display data on their website without having personal access to the external server (like pulling Twitter data).

Generally speaking there are four commands used to access RESTful APIs:

GET for retrieving an object
POST for creating a new object
PUT for modifying or replacing an object
DELETE for removing an object

Each of these methods should be passed with the API call to tell the server what to do.

The vast majority of web APIs only allow GET requests to pull data out from an external server. Authentication is optional, but certainly a good idea when allowing potentially damaging commands like PUT or DELETE.

However not many RESTful APIs even go this far. Consider Pokéapi which is a free Pokémon API database. It’s open to the public with decent rate limiting (limiting users to a certain number of API requests over a period of time), but only allows the GET method for accessing resources. This may be colloquially termed a consumption-only API.

Return types are also important, and should retain homogeneity for all resources. JSON is a popular return type with online specs that explain proper data structures.

RESTful APIs use nouns for API objects, and verbs for performing actions on those objects. Authentication may be part of this, rate limiting may also be part of this. But a very simple API can get by without much concern to user limitations.

Accessing API Resources

Public APIs are typically accessible from direct website addresses. This means the URL structure is important, and should be used only for API requests.

Some URLs can include a prefix directory like /v2/ for an updated version 2 of a previous API. This is common for developers who don’t want to depreciate their 1.x API, but still want to offer the newest structure.

I really enjoyed this post covering basic URL structures and examples from other services.

Note that the endpoint’s return data will change dramatically based on the HTTP method. For example, GET retrieves content, while POST creates new content. The request could point to the same endpoint, but the result could be very different.

reddit api documentation website — IMAGE: Reddit API Documentation

Looking over examples online may help you understand concepts clearer. We already saw the Pokeapi, but here are some other real-world API examples to peruse:

Building Your Own API

The process of constructing your own API shouldn’t be taken lightly but it’s also not as complicated as you might think. It does take an understanding of API design patterns and best practices to build something of real value.

Each API must connect to your server to return data of some kind. Not only do you need to write code to do that, but you also need for format the return data. Other potential requirements include authentication and rate limiting, so building an API is certainly not for the faint of heart.

But let’s take a look at some basic tenets of API architecture.

Build Endpoints

One aspect of API development is building endpoints. When creating resources you want to use nouns, not verbs. This means API data should be returning a person, place, or thing, most often it’s a thing with specific attributes (for example a tweet and all its metadata).

It can be difficult learning to name nouns, but this is a crucial aspect of API development. Simplification is best whenever possible.

A big debate is singular vs. plural nouns. If you were making a Twitter API you might have the object group first (i.e. tweet), then the object item second (i.e. tweet ID).

$ /tweet/15032934882934
$ /tweets/15032934882934

In this case, I’d argue the singular form looks better. This is true especially when only one resource is being returned. But there is no documented 100% correct answer, so do whatever fits best for your project.

Set Return Type

Another consideration is return type data. Most web users expect JSON content, so that’s likely the best option. XML is another choice if you want to offer both. However JSON is the fundamental API return type among web developers.

There’s a lot more that goes into API development, so I recommend playing with APIs first. This way you can see how other developers build their APIs, and hopefully you’ll grow familiar with the typical requirements.

If you’re just getting started, please consider skimming these dev tutorials:

Further Resources

The best way to learn web app development is through practice. Granted theory is always worth studying, because it allows you to converse with developers and understand how things work.

But a good place to start with API development is connecting into other APIs first. Learn the basics of client-side connections, and from there you can move onto server-side API development by creating your own API from scratch.

If that’s your goal, please consider the following resources to help along your journey.