Communicating with the Outside World

"An API that isn't comprehensible isn't usable."

- James Gosling

All software systems eventually need to exchange data with the outside world. In many cases, this is achieved via an API. This chapter provides a comparison between the REST and RPC patterns for building APIs and discusses some common API issues such as authentication, versioning, and security. The rest of this chapter explores the gRPC ecosystem in depth and concludes with a gRPC-based API implementation for the Links 'R' Us project.

The following topics will be covered in this chapter:

• Basic principles of RESTful APIs
• Strategies for securing APIs and pitfalls that you should avoid
• Approaches for API versioning
• gRPC as an alternative to building high-performance services
• Describing messages and RPC services using the protocol buffers definition...

Technical requirements

The full code for the topics discussed that will be within this chapter have been published to this book's GitHub repository in the Chapter09 folder.

You can access this book's GitHub repository, which contains the code and all the required resources for each of this book's chapters, by pointing your web browser to the following URL: https://github.com/PacktPublishing/Hands-On-Software-Engineering-with-Golang.

To get you up and running as quickly as possible, each example project includes a Makefile that defines the following set of targets:

Makefile target	Description
deps	Install any required dependencies
test	Run all tests and report coverage
lint	Check for lint errors

As with all the other chapters in this book, you will need a fairly recent version of Go, which you can download at https://golang.org/dl.

...

Designing robust, secure, and backward-compatible REST APIs

Whenever an engineer hears the word API, REST, the acronym for Representational State Transfer, is undoubtedly one of the first words that springs to mind. Indeed, the vast majority of online services and applications that people use on a daily basis are using a REST API to communicate with the backend servers.

The proliferation of what we commonly refer to as RESTful APIs is indeed not coincidental. REST, as an architectural style for building applications for the web, offers quite a few enticing advantages over alternatives such as the Simple Object Access Protocol (SOAP):

• Ease of interaction: A web browser or a command tool such as curl is all that is required to interact with REST endpoints
• The majority of programming languages ship with built-in support for performing HTTP requests
• It is quite easy to intercept...

Building RPC-based APIs with the help of gRPC

gRPC ^[2] is a modern open source framework that was created by Google to assist the process of implementing APIs that are based on the Remote Procedure Call (RPC) paradigm. In contrast to the REST architecture, which is more suited for connecting web-based clients such as browsers to backend services, gRPC was proposed as a cross-platform and cross-language alternative for building low-latency and highly scalable distributed systems.

Do you know what the letter g in gRPC stands for? A lot of people naturally think that it stands for Google, a reasonable assumption given that gRPC was released by Google in the first place. Others believe that gRPC is a recursive acronym, that is, gRPC Remote Procedure Calls.

The fun fact is that both interpretations are wrong! According to the gRPC documentation on GitHub, the meaning of the letter...

Decoupling Links 'R' Us components from the underlying data stores

Both the link-crawler component that we created in Chapter 7, Data-Processing Pipelines, and the PageRank calculator component that we built in Chapter 8, Graph-Based Data Processing, were designed to work with one of the data store implementations from Chapter 6, Building a Persistence Layer.

To this end, when configuring these components, we are expected to provide suitable concrete data store implementations that satisfy the graph.Graph and index.Indexer interfaces. If we were building a monolithic application, we would normally be performing this bit of initialization inside the main package, as follows:

1. Import the package with the data store drivers we want to use in our application (for example, the CockroachDB backed link-graph and the Elasticsearch backed text indexer).
2. Create new driver instances...

Summary

In the first part of this chapter, we discussed the key principles behind RESTful APIs. We focused on effective strategies for handling hot topics such as security and versioning. Then, we analyzed the pros and cons of RESTful APIs compared to the RPC-base paradigm used by the gRPC framework and highlighted the key differences that make gRPC more suitable for building high-performance services.

Now that you're at the end of this chapter, you should be familiar with the protocol buffer definition language and know how to leverage the various features supported by the gRPC framework for building high-performance secure APIs based on the RPC pattern.

In the next chapter, we will find out how we can perform hermetic builds of our software, package it as a container image, and deploy it on a Kubernetes cluster.

Questions

1. Describe the CRUD endpoints for a user entity.
2. Explain how basic authentication over TLS can help us secure APIs.
3. Are TLS connections immune to eavesdropping?
4. Describe the steps in the three-legged OAuth2 flow.
5. What is the benefit of using protocol buffers compared to JSON for request/response payloads?
6. Describe the different RPC modes that are supported by gRPC.

Further reading

1. A Go web development eco-system, designed to make your life easier; refer to the following link for more information: https://github.com/gobuffalo/buffalo.
2. A high performance, open-source universal RPC framework; refer to the following link for more information: https://www.grpc.io.
3. A high-performance HTTP request router that scales well; refer to the following link for more information: https://github.com/julienschmidt/httprouter.
4. A high productivity, full-stack web framework for the Go language; refer to the following link for more information: https://github.com/revel/revel.

5. A powerful HTTP router and URL matcher for building Go web servers; refer to the following link for more information: https://github.com/gorilla/mux.
6. Berners-Lee, T.; Fielding, R.; Masinter, L.: RFC 3986, Uniform Resource Identifier (URI): Generic Syntax.
7. Developer guide for protocol...