Serverless Handbook

Student Login

Creating a REST API

You've heard of REST before, but what is REST? How does it work? Can you build one from scratch? Does serverless make your REST life easier?

In this chapter, learn about REST best practices and finish with a small implementation you can try right now. I left mine running ✌️

What is REST

REST stands for REpresentational State Transfer. Coined in Roy Fielding's 2000 doctoral thesis, it now represents the standard approach to web APIs.

Fielding says REST is an architectural principle. It recommends how to build a scalable web system, but there's no official standard.

You may have noticed this in the wild. RESTful APIs follow similar guidelines and no two are alike.

These days any API that uses HTTP to transfer data and URLs to identify resources is called REST.

Here are the 6 architectural constraints that define a RESTful system 👇

  • client-server architecture specifies a separation of concerns between the user interface and the storage of data. This simplifies both sides and lets them evolve independently.
  • statelessness specifies that the protocol is stateless. Each request to the server contains all information necessary to process that request. Servers do not maintain client context.
  • cacheability specifies that clients can cache any server response to improve performance on future requests. Servers have to annotate responses with appropriate caching policies via http headers
  • layered system means that, like regular HTTP, a RESTful client shouldn't need to know whether it's talking to a server, a proxy, or load balancer. This improves scalability.
  • code on demand (optional) says that servers can send executable code as part of their responses. You see this with web servers sending JavaScript.
  • uniform interface is the most fundamental and means that clients can interact with a server purely from responses, without outside knowledge.

A uniform interface

Creating a uniform interface is the most important aspect of a RESTful API. The less clients know about your server, the better.

Each request identifies the resource it is requesting. Using the URL itself.

Responses send a representation of a resource rather than the resource itself. Like compiling a set of database objects into a JSON document.

All messages are self-descriptive meaning both client and server can understand a message without external information. Send everything you need.

A resource's representation includes everything needed to modify that resource. When clients get a response, it should contain everything necessary to modify or delete the underlying resources.

Academics say responses should list possible actions so clients can navigate a system without intimate knowledge of its API. You rarely see this in the wild.

Designing a RESTful API

The trickiest part of building a RESTful API is how it evolves over time. The second trickiest is keeping it consistent across your app.

As your system grows you're tempted to piggy-back on existing APIs and break resource constraints. You're likely to forget the exact wording and phrasing of different parts.

All that is natural. The important part is to start on the right foot and clean up when you can.

Engineers are human

When engineers can do something with your API, they will.

They're going to find every undocumented feature, discover every "alternative" way to get data and uncover any easter egg you didn't mean to include. They're good at their job.

Do yourself a favor and aim to keep everything consistent. The more consistent you are, the easier it will be to clean up.

That means

  • all dates in the same format
  • all responses in the same shape
  • keep field types consistent, if an error is a string it's always a string
  • include every field name and value in full
  • when multiple endpoints include the same model, make it the same

Here are tips I've picked up over the past 14 years of building and using RESTful APIs.

URL schema

Your URL schema exists to solve one problem: Create a uniform way to identify resources and endpoints on your server.

Keep it consistent, otherwise don't sweat it.

Engineers like to get stuck on pointless details, but it's okay. Make sure your team agrees on what makes sense.

When designing a URL schema I aim to:

  • make it guessable, which stems from consistency and predictability
  • make it human readable, which makes it easier to use, debug, and memorize
  • avoid query strings because they look messy and can make copy paste debugging harder
  • avoid strange characters like spaces and emojis. It looks cute, but it's cumbersome to work with
  • include IDs in URLs because it makes debugging and logging easier

The two schemas I like, go like this:<namespace>/<model>/<id>

Using an api.* subdomain helps with load balancing and using special servers for your API. Less relevant in the serverless world because providers create unique domains.

The optional <namespace> helps you stay organized. As your app grows, you'll notice different areas use similar-sounding names.

You don't need a namespace for generic models like user or subscription.

Adding a <model> that's named after the model on your backend helps you stay sane. Yes it breaks the idea of total separation between client and server, but it's useful to maintain consistency.

If everyone calls everything the same name, you never need to translate. 😉

The <id> identifies the specific instance of a model that you're changing.

Sometimes it's useful to use this alternative schema:<namespace>/<model>/<verb>/<id>

The verb specifies what you're doing to the model. More on that when we discuss HTTP verbs further down.

Data format

Use JSON. Both for sending data and for receiving data.

Hello! 👋

Are you a frontend engineer diving into backend? Do you have just that one bit of code that can't run in the browser? Something that deals with secrets and APIs?

That's what cloud functions are for my friend. You take a JavaScript function, run it on serverless, get a URL, and voila.

But that's easy mode. Any tutorial can teach you that.

What happens when you wanna build a real backend? When you want to understand what's going on? Have opinions on REST vs GraphQL, NoSQL vs. SQL, databases, queues, talk about performance, cost, data processing, deployment strategies, developer experience?


Unlock your free chapter!

Access to this chapter immediately, extra free chapter and Serverless crash course in your email ✌️

I like privacy too. No spam, no selling your data.

buy now amazon

Dive into modern backend. Understand any backend

Serverless Handbook shows you how with 360 pages for people like you getting into backend programming.

With digital + paperback content Serverless Handbook has been more than 1 year in development. Lessons learned from 14 years of building production grade websites and webapps.

With Serverless Handbook, Swiz teaches the truths of distributed systems – things will fail – but he also gives you insight on how to architect projects using reliability and resilience perspectives so you can monitor and recover.

~ Thai Wood, author of Resilience Roundup

If you want to understand backends, grok serverless, or just get a feel for modern backend development, this is the book for you.

Serverless Handbook full of color illustrations, code you can try, and insights you can learn. But it's not a cookbook and it's not a tutorial.

Serverless Handbook on your bookshelf
Serverless Handbook on your bookshelf

Yes, there's a couple tutorials to get you started, to show you how it fits together, but the focus is on high-level concepts.

Ideas, tactics, and mindsets that you need. Because every project is different.

The Serverless Handbook takes you from your very first cloud function to modern backend mastery. In the words of an early reader:

Serverless Handbook taught me high-leveled topics. I don't like recipe courses and these chapters helped me to feel like I'm not a total noob anymore.

The hand-drawn diagrams and high-leveled descriptions gave me the feeling that I don't have any critical "knowledge gaps" anymore.

~ Marek C, engineer

If you can JavaScript, you can backend.

Plus it looks great on your bookshelf 😉

buy now amazon


Where to store data
Using GraphQL
Created bySwizecwith ❤️