1

Introduction to APIs

In today's highly connected, highly competitive world, where the efficacy of processes can mean the difference between success and failure, one of the most important players, from a technology standpoint, is application programming interfaces (APIs). They help us connect our systems, automate processes in those systems, and adapt those systems to our needs instead of our needs to those systems. All that is done thanks to APIs.

This book will explore how to build APIs in Go from scratch. We'll start with the basics of an API and how to explore it. Then, we'll go through the incremental process of creating an API, from adding the basic endpoints to incorporating things such as security and telemetry. As an optional exercise, we'll use a web framework instead of the standard library and an ORM instead of SQL queries.

In this chapter, we'll cover the following topics:

• The different kinds of APIs
• The basic concepts around REST APIs
• How to build a very basic API in Go

But let's start from the beginning. What exactly is an API? Let's talk about this.

Getting the most out of this book - get to know your free benefits

Unlock exclusive free benefits that come with your purchase, thoughtfully crafted to supercharge your learning journey and help you learn without limits.

Here's a quick overview of what you get with this book:

Next-gen reader

Figure 1.1: Illustration of the next-gen Packt Reader's features

Our web-based reader, designed to help you learn effectively, comes with the following features:

Multi-device progress sync: Learn from any device with seamless progress sync.

Highlighting and notetaking: Turn your reading into lasting knowledge.

Bookmarking: Revisit your most important learnings anytime.

Dark mode: Focus with minimal eye strain by switching to dark or sepia mode.

Interactive AI assistant (beta)

Figure 1.2: Illustration of Packt's AI assistant

Our interactive AI assistant has been trained on the content of this book, to maximize your learning experience. It comes with the following features:

Summarize it: Summarize key sections or an entire chapter.

AI code explainers: In the next-gen Packt Reader, click the Explain button above each code block for AI-powered code explanations.

Note: The AI assistant is part of next-gen Packt Reader and is still in beta.

DRM-free PDF or ePub version

Figure 1.3: Free PDF and ePub

Learn without limits with the following perks included with your purchase:

Learn from anywhere with a DRM-free PDF copy of this book.

Use your favorite e-reader to learn using a DRM-free ePub version of this book.

Unlock this book's exclusive benefits now

Scan this QR code or go to packtpub.com/unlock, then search for this book by name. Ensure it's the correct edition.

Note: Keep your purchase invoice ready before you start.

Technical requirements

All the code examples for this chapter are included in this book's GitHub repository: https://github.com/PacktPublishing/Modern-REST-API-Development-in-Go. You only need the Go compiler installed on your system to compile and execute the code.

What's an API?

One of the first questions we should answer here is, what's an API? As mentioned in the introduction, it's an application programming interface, but what does that even mean?

In general terms, it's an interface for programmers to interact with an application. However, there are different definitions of an API, depending on the context. One of them could be the set of methods/functions that are exposed by a library. That's known as a library API. Of course, as a software engineer, you're dealing with these kinds of APIs all day long - your Go packages, your exported functions, and the standard library are all APIs, but they focus on in-process communication, organizing your code, and separating concerns. But, in modern systems, when we talk about APIs, we're usually talking about remote APIs.

So... what's a remote API? A remote API is a set of functionalities that are exposed to other processes, generally through a communication channel (such as a socket), allowing independent programs to interact with each other.

But that's still abstract, so let's be more specific about what we'll discuss in this book. We'll talk specifically about REST APIs, one of the most common ways of inter-process communication used today. In REST, the communication channel that's used is an HTTP connection that uses the HTTP protocol, so the API behaves like a web server and uses the same technology to communicate with other processes.

Before we explore REST and why we chose it over other options (maybe the best option for you is a different one), let's explore the most popular options that are available.

GraphQL

GraphQL is one of the modern approaches to providing APIs. It was born from the necessity to provide more flexible APIs to consumers without enforcing a rigid structure (REST APIs are normally less flexible for consumers). It has a lot of exciting advantages, such as the ability to request only specific fields or embed substructures in the same response on demand by asking the client for it. That's all doable in REST, but it isn't standardized like it is in GraphQL. GraphQL is a great option when many clients access your data in very different ways and patterns, and you must provide that flexibility. Also, GraphQL provides lots of value when you don't know how the consumer will query your data.

gRPC

gRPC Remote Procedure Calls (gRPC) is also one of the newest approaches for creating APIs. It's widely used in Go and has a lot of advantages. One of the main advantages is that it's agnostic from the language, and most of the code for serialization/deserialization and remote calls is automatically generated by the tools available. The degree of communication performance in gRPC is outstanding for multiple reasons, but mainly due to its binary protocol and usage of HTTP 2 as the transport layer. gRPC is ideal for the internal communication of services/microservices but isn't widely used in things such as web applications or public APIs. This is because HTTP 2 is a requirement and developers are normally more familiar with other technologies, such as REST.

SOAP

Simple Object Access Protocol (SOAP) is a very old technology that uses similar principles to gRPC. It uses HTTP as a transport layer, and the protocol is 100% XML. The main problem with SOAP is that compatibility between libraries is suboptimal. SOAP works well when you use the same library and language in all the services that you're communicating with, but not so well when you have a heterogeneous environment. Also, web clients rarely use SOAP as a communication protocol.

Custom API

You can build a custom API mechanism, selecting how you serialize and deserialize the data, transport it, and define the actions you allow. You could define a whole protocol and use TCP to communicate directly, but that's normally not needed, and there are a lot of problems that have already been solved in the previously explained technologies and, of course, in REST.

I'm adding this option for completeness, but unless you know why you're deciding to go with this option, you should probably be using one of the existing well-known solutions.

In summary, there are multiple mechanisms for generating APIs and communicating with applications, but in this book, we'll be using REST. So, what's REST, and why should you use it?

What's REST?

Representational State Transfer (REST) is one of the most common ways of building remote APIs in modern software, especially on public APIs that need to be consumed by third-party services/clients. The main reasons why REST is so widely used are the simplicity of the concepts it embraces and its flexibility to adapt whenever those concepts don't 100% apply to your use case.

I'm going to take a...