How to Build a RESTful API in Go (Overview)

If you've been following my more recent blog posts and tutorials, you'll know that I've been spending ever more time learning Go. Now that I feel I've learned enough, I want to start sharing that knowledge. So, since I love building web-based apps and APIs, I figure that was the best thing to talk about.

Prerequisites

Before we get too far along, to get the most out of this series, you're going to need a few things (not too many):

• Go (naturally)
• Your preferred code editor or IDE. I use Visual Studio Code.
• A tool for making requests, such as curl or Postman
• Docker Engine.
• Some prior experience with Docker, containers, and unit testing would be helpful, but isn't necessary. So don't worry if these topics are all pretty new to you.

Series overview

In this, the series introduction, let's set out what you can expect to achieve over the course of the series.

• Series Introduction: Broad introduction to the series
• Part One: Create the core of the (RESTful) API. It won't be an example of best practices, but it will work.
• Part Two: Refactor the API so that it's better organised and much more maintainable
• Part Three: Add tests so that you can be comfortable knowing that it works as expected
• Part Four: Add logging so that you can debug the API if it doesn't work as expected
• Part Five: Add some middleware so that the application is more secure
• Part Six: Deploy the application using Google Cloud Run

What Will You Learn?

What I hope you'll get from this series isn't to become a security or encryption expert. That aspect of the application is quite arbitrary (if I'm honest). I picked encryption and decryption as I felt that it's sufficiently involved such that it makes for a meaningful example to build an application around.

Rather, I hope that, by the end of the series, you'll feel comfortable building and deploying API in Go. Will you learn absolutely everything that you could know? Naturally, no. Like any topic, that takes a lot of time, patience, persistence — and more than one resource. However, by the time you're finished, you will have the essential knowledge.

Application Overview

As I started to cover earlier in the tutorial, you're going to build a RESTful API that can encrypt and decrypt text. It won't be a world-class one, following best practices, but it will work. Now, let's dive into a litte bit more detail.

The API will have two endpoints:

encrypt

This endpoint will accept POST requests to encrypt (or cipher) a plain text string. The plain text will be stored in the data parameter. If present and not empty, the text will be encrypted using AES-256 and set as the body of the response. For example

curl -i --form "data=Matthew Setter" http://localhost:4000/encrypt

HTTP/1.1 200 OK
Date: Fri, 08 Sep 2023 09:38:04 GMT
Content-Length: 42
Content-Type: text/plain

??j!N??   by???8YJ?t?՟?f<?:??6v@s???p??

decrypt

This endpoint will accept POST requests to decrypt ciphered text. The encrypted text will be stored in the data parameter. If present and not empty, the encrypted text will be decrypted and returned as the body of the response. bash curl -i --form "data=..." http://localhost:4000/decrypt

If you're not a math or encryption expert, don't worry. You don't need to be. I'm not either, but have learned a lot as I built the application. To avoid being an expert, the application will use three packages from Go's standard library Crypto package:

• aes: This package implements AES (Advanced Encryption Standard) encryption.

• cipher: Quoting the package's documentation:

  It implements standard block cipher modes that can be wrapped around low-level block cipher implementations.

  In short, it simplifies working with crypto/aes to encrypt (cipher) and decrypt (decipher) text.

• rand: This package, implements a cryptographically secure random number generator, which is necessary to ensure that the encryption is not easy to break.

Are you keen?

If you are, then dive in to part one, and let's start building an API in Go, together!