Getting Started with a RESTful API

This five-part series will show you how to build an API from the ground-up using Node's Express and AWS DynamoDB.

We'll build an API that simply reads and writes data about bikes, a perfect start for an e-commerce shop. We'll also be using Cyclic to host our API for free, including the DynamoDB storage.

But before we start with the coding, let's start with a description of what servers and APIs really are.

Got lost?

You can check out this project's full code on GitHub to stay up-to-date with the tutorial.

A quick refresher on server-side programming

How servers power the Internet

Browsers and web servers communicating back-and-forth using HTTP requests and responses.

Before we delve deeper into RESTful APIs, let's start from its origins and make sure that we all agree on what a web server is.

From a hardware point-of-view, a web server is a physical computer that stores and serves data over the Internet, and that includes everything from HTML documents, CSS stylesheets, images and video files.

Furthermore, every web server must run an HTTP server. That's a piece of software that takes-in URLs and processes them to deliver content back to the end-users, while using the HTTP protocol to facilitate the sharing of information over the Internet.

tip

And if the URL is wrong, the server will generate a response with the infamous 404 code instead.

Servers communicate with browsers using the HTTP protocol

When you search for a product, view details on it or even buy it, an HTTP request is sent to a web server.

HTTP is a web standard that allows any server to know what to expect when it receives an HTTP request:

a URL linking to the resource,
request parameters defined in the query string, (like google.com/?q=my%20search)
a method defining the desired action, (whether to get, create or delete that resource)
JSON data encoded in the request body or in associated cookies.

HTTP servers proceed by processing the request, then sending an HTTP response back to the sender. The response includes a status line indicating the result of that operation. Success for example, is represented with the HTTP/1.1 200 OK code. Unavailable resources would instead respond with the HTTP/1.1 404 NOT FOUND code.

And just like any other resource, static websites are just HTML files hosted on web servers. (with a hint of CSS files, JS files and other media)

Sounds good, we just learnt that servers are the building-blocks of the Internet, and that they're responsible for storing static resources and serving them back to the users of the Internet.

But what about websites that are always changing? Think Walmart, for example. It's an online store that's constantly changing:

adding new products,
tracking how many articles of an item are in-stock,
and storing private user-specific data, such as shopping carts.

These kinds of websites, which may even be categorized as full-fledged applications, are usually using an API (Application Programming Interface) behind the scenes.

Instead of delivering whole HTML files, APIs only return useful information (usually in JSON format) that may be used to build a website. For instance, the Walmart API may have one URL for retrieving the list of items in display:

[
  {
    "name": "Oranges",
    "inStock": 8,
    "description": "..."
  },
  {
    "name": "Table",
    "inStock": 0,
    "description": "..."
  }
]

It may fetch this data from a database that's maintained by an entirely different department in Walmart. The sender of the HTTP request, then, can solely focus on using this information to build a website and show it to the end-user.

Web servers are critical in the creation of APIs that rely on dynamic data:

they efficiently deliver tailored-made recommendations to your users,
they power dynamic search results and e-commerce products inventory,
and they give control access to private user information.

With this kind of separation, our website can use JavaScript to fetch data from our API and then use a client-side framework such as React to build the end-user interface.

Furthermore, server-side code can be written in a variety of programming languages, including but not limited to PHP, Python, Ruby, and C#. But why stray away from the same language that we already use in client-side programming?

With Node, we're able to write our back-end code in JavaScript, giving us full access to the server operating system. (storage, networking, scheduling, and more.) It runs directly in the server operating system, while adding new modules including HTTP and file-system libraries.

When both the front-end and back-end sides of an application are written in the same language, developers experience less of "context shift", making it ideal for large-scale projects.

// Example of a web server written in Node

const http = require('http');
const fs = require('fs');
const path = require('path');

http
  .createServer((request, response) => {
    console.log(`request ${request.url}`);

    let filePath = `.${request.url}`;
    if (filePath === './') {
      filePath = './index.html';
    }

    const extname = String(path.extname(filePath)).toLowerCase();
    const mimeTypes = {
      '.html': 'text/html',
      '.js': 'text/javascript',
      '.css': 'text/css'
    };

    const contentType = mimeTypes[extname] ?? 'application/octet-stream';

    fs.readFile(filePath, (error, content) => {
      if (error) {
        if (error.code === 'ENOENT') {
          fs.readFile('./404.html', (error, content) => {
            response.writeHead(404, { 'Content-Type': 'text/html' });
            response.end(content, 'utf-8');
          });
        } else {
// ... and much more code!

But writing your own server in Node itself isn't very practical. Many tasks such as handling different HTTP verbs (like GET and POST) for the same route aren't supported in Node by default, meaning that you'd have to reinvent the wheel by making your own web framework!

// Example of web server written with Express

const express = require("express");
const app = express();
const port = 3000;

app.get("/", (req, res) => {
  res.send("Hello World!");
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Thankfully, Node comes with its own package manager, giving us access to a plethora of community-made modules. One of those modules is Express, the most popular Node web framework. It comes with a variety of features out of the box:

Handling requests for the same URL with different HTTP verbs,
Parsing JSON data straight from HTTP requests,
Reading query data straight from HTTP requests,
Running "middleware" for any routes before handling the requests. (Useful for authentication)

Express also comes with its own bundle of community-made middleware to handle all kinds of necessities such as parsing cookies and security headers. We'll be using Express in the remainder of this tutorial.

Let's understand RESTful APIs

A RESTful API communicating with the browser through a variety of HTTP actions, and relaying those to a database.

Server-side programmers have the ability to build their APIs however they want. That's the freedom that Node and Express give you:

you get to name your own routes,
you get to handle different HTTP verbs in any way you want,
and you even get to format the responses in whichever way you desire.

But with all this freedom comes a problem: we want all APIs to be unified under one standard; one way of formatting routes; one way of handling HTTP verbs; and one way of sending responses.

That's where REST comes in; it stands for "Representational State Transfer" and defines a universal standard for building APIs.

REST recommends building your API around database(s), where each URL links in one way or another to one or more resources in that database.

REST calls for the use of the following HTTP verbs:

GET is for fetching the resource.
POST is for creating the resource.
DELETE is for deleting the resource.
PUT is for updating the whole resource.
PATCH is for updating parts of the resource.

caution

It's important that GET (also known as a "Safe method") requests do not change anything about the database.

RESTful APIs handle routes in an idempotent manner, meaning that making the same request multiple times yields the same result. They must also be stateless, meaning that all necessary data to handle the request is contained within the request itself and not remembered from a previous request. This makes RESTful APIs much more scalable than their counterparts.

Developers use cURL to debug their APIs, a Linux command that comes pre-installed on most modern distributions.

Let's demonstrate it on the RESTful API that we'll be making in this tutorial.

For starters, it's incredibly easy to make GET requests:

curl https://bikes.cyclic.app/bikes/all