gRPC and Server Side Swift: Getting Started

gRPC tools are powerful when working across many teams or in distributed teams. This is because, in addition to server-side Swift, the gRPC tools can generate code for Swift, Objective-C, Java, Kotlin and many other languages.

Working with gRPC allows you to define an API and generate networking and object model code for use on your server and any client.

In this tutorial you’ll learn how to define an API based on gRPC and how to leverage its tools to generate code for Server Side Swift and client apps. You’ll learn how to:

• Read and change a .proto file that describes an API.
• Exercise a gRPC API with Evans.
• Use the protoc command line tool to generate Swift code for your server.
• Replace the default HTTP server in a Vapor app with a gRPC server.
• Use gRPC to provide a CRUD service based on Fluent and PostgreSQL.

This tutorial also assumes you have experience using Vapor to build web apps. See Getting Started with Server-Side Swift with Vapor 4 if you’re new to Vapor.

Getting Started

Download the starter project by clicking the Download Materials button at the top or bottom of this tutorial.

The starter project contains a Vapor app for managing TODO items. Some of the pieces aren’t there as you won’t be using the webserver capabilities of Vapor.

Along with the project, you need to download and install other tools for working with gRPC. The sections below detail the steps for installing protoc, Evans, and the grpc-swift plugins on macOS or Linux. Skip ahead if you already have them installed.

In this tutorial, you’ll use Swift Package Manager to set gRPC as a dependency for the Vapor server. You’ll use the protoc code generator and Swift language plugins to generate Swift code from a .proto file. Finally, you’ll use Evans to act as the client for your server.

Installing Evans

Evans is the gRPC version of something like cURL or Insomnia which allows you to make calls to a server that uses gRPC without having to write an entire client app first. Evans is also a quick way to check a .proto file for errors.

On macOS, Evans is available via Homebrew. To install it, type the following in Terminal:

brew tap ktr0731/evans && brew install evans

On Linux the builds are available on GitHub.

After you install Evans, confirm it’s working by checking the output of this command in the Terminal:

evans --version

Installing Protoc and the Swift Plugins

To generate the Swift code from a gRPC spec file you need:

• The protoc executable.
• The plug-ins for Swift: one for generating Swift code for Message items and one for generating Service items.

On macOS, both are available in homebrew. In Terminal, type:

brew install swift-protobuf grpc-swift

The GitHub repo for grpc-swift contains more tutorials and demos of other features of the Swift implementation of gRPC, you may want to clone this to get the Swift translators for Linux. If you are running macOS, you can skip the rest of this section.

For Linux, protoc is available as a binary from GitHub. After extracting the binary and placing it somewhere in your PATH, confirm that everything works by checking on the version by typing the following into Terminal:

protoc --version

On Linux, protoc comes with translators for Java, Kotlin, Python, and other languages, but not Swift. To get the Swift translators for Linux, clone the Swift gRPC project.

git clone https://www.github.com/grpc/grpc-swift <some directory>

The project has a number of make scripts. Generate the plugins by navigating to the root of the project and typing:

make plugins

Now, copy the protoc-gen-grpc-swift and protoc-gen-swift files into the same directory as your protoc executable.

Whew! All the tools are in place, and it’s time to write some code. :-]

Adding gRPC Support to Vapor

For Swift, gRPC runtime support is available as a standard Swift package. Open the Package.swift file in the sample project and add the following to the dependencies array:

.package(url: "https://github.com/grpc/grpc-swift.git", from: "1.0.0"),

Next, in the app dependencies section add a reference to the package:

.product(name: "GRPC", package: "grpc-swift"),

Now, build the project to ensure that all packages have been correctly configured.

Open Terminal, navigate to the root of the project and type the following:

swift build

This will pull all the dependencies and build your Vapor app. This process can take a while, so in the meantime, you can learn some more details about gRPC.

Learning About gRPC

gRPC is a technology developed at Google to help you define and maintain an app interface. It has tools and plugins that generate native networking and object models code for the server and client to use with the interface.

It has many similarities to OpenAPI. Both are solving a similar problem; how to build, document and maintain APIs that are usable by different clients in different languages and at different organizations.

gRPC generates server and client code from the same spec, encoded in a .proto file, regardless of the programming language used.

This helps ensure that the code is less prone to errors caused by typos in a URL or field name. Since gRPC handles the network transport, developers don’t have to write specific code to support network calls.

How is gRPC Different from REST?

The most common way you’ve probably worked with APIs is using a REST interface with JSON. These technologies were initially built for web browsers to talk to web servers. Servers with RESTful APIs organize around URL paths and use HTTP verbs such as; GET, POST etc., to determine what resource to send to the client.

When working with a RESTful server, you usually have to encode and decode JSON data and have HTTP stack functions. Any client that can read JSON data over an HTTP connection can use a RESTful API.

gRPC sets out to make the calls to a remote server look and act like calls to other local parts of an app. Instead of constructing a URL and encoding JSON to send over HTTP, your app calls a function or method and gRPC handles encoding the data to a compact format, then transmits the data.

Additionally, gRPC uses HTTP/2 which allows for APIs to stream data. You won’t stream data in this tutorial, but there are examples in the grpc-swift repo.