Building API Services: A Beginner’s Guide

Last updated: Feb 25, 2019

This document provides an overview of general practices and technologies for building HTTP RESTful and/or gRPC API services. It is the opening piece of the Build API Services: A Beginner’s Guide tutorial series.

Getting started

APIs are a set of methods that facilitate communications between software components, allowing systems to retrieve information or instruct another piece of software to perform some actions. The browser you are using, for instance, calls a large number of operating system APIs when you open this page, so that it can connect to the network, process the HTML source code and display it on the screen. Thanks to the ever growing popularity of mobile computing and cloud technologies, nowadays when people talk about APIs, they are usually referring to Networked APIs, that is, APIs operating across a network of devices, such as Google Custom Search. In this tutorial series, terms API and Networked API are used interchangeably.

Complicated as it may sound, creating a basic API service is actually quite easy. Snippet below defines an API service using Python and Flask that allows everyone to retrieve a predefined list of users:

If you are merely prototyping, such a basic API service would suffice. However, building a production ready API service takes much more engineering effort. In general, you need to:

• Design APIs with simplicity, consistency, discoverability, and usability in mind
• Prepare server-side (and client-side) apps and libraries, preferably with an automated workflow
• Set up authorization and authentication

Additionally, you should:

• Deploy your API service to a platform that is secure, scalable and highly available
• Set up logging, monitoring and tracing to keep your API service up and running
• Set up quotas and traffic management policies to control overflows
• Set up data analytics to gather usage insights
• Provide easy-to-understand documentation and supporting materials

This tutorial series largely focuses on building API services. We will talk more about API service deployment and management in another time.

Technologies

There are many protocols, tools and frameworks you can use to create API services. In this tutorial series you will learn about two major types of APIs, HTTP REST APIs and gPRC APIs, and the tools that can help you build them.

REST, HTTP RESTful APIs, and OpenAPI

Representational State Transfer (REST) is an architectural style that describes a web interaction model. It follows resource oriented design, which breaks down a service into a collection of resources and a set of methods (verbs) that can be used to manipulate resources. Each resource is assigned a resource name and represented in a format of developer’s choice. For example, to retrieve a photo, a client can specify a resource name along with a method (GET) in a request, and send the request to the server; the server will then return the requested resource to the client in the specified format:

APIs that conform to REST and use HTTP protocol (usually HTTP/1.1) are HTTP RESTful APIs. Developers often use data formats JSON (JavaScript Object Notation) and/or XML (Extensible Markup Language) to transfer data in HTTP REST APIs. You may use any web framework to build an HTTP REST API service, popular choices include flask (Python) and express.js (Javascript/Node.js).

You may build an HTTP RESTful API service piece by piece in the same fashion as developing a web application; however, many developers find it easier to leave the task to computers. With a specification of your API service, many tools can prepare server-side and client-side code automatically for you. This approach greatly reduces development workload, and also helps clients better consume your APIs. In this tutorial, you will use OpenAPI 3.0 to specify your APIs and OpenAPI Generator to prepare the code.

OpenAPI is a specification for machine-readable HTTP RESTful APIs, allowing developers to describe their APIs in YAML or JSON. It is managed by OpenAPI Initiative, an open source collaborative project under the Linux Foundation. OpenAPI Generator is community-driven open-source tool that reads your OpenAPI specification and prepares server-side and client-side artifacts for you.

gRPC and Protocol Buffers

gRPC is an open-source RPC framework developed by Google. It uses HTTP/2 for transportation and offers many useful features such as bi-directional streaming and integrated authentication. APIs that use gRPC framework are gRPC APIs. It is recommended that gRPC APIs also adopt resource oriented design as architectural style.

gRPC APIs usually leverage Protocol Buffers to exchange data. Protocol Buffers, similar to JSON and XML, is a Google-developed, open-source mechanism for data serialization. The serialization process requires that you first specify the structure of your data in a .proto file using the Protocol Buffers language (.proto file syntax); this step is also known as defining a Protocol Buffers message type. Protocol Buffers compiler can then read the .proto file, and compile your data structure into a class in the language of your choice, which you may use to manipulate your data programmatically.

gRPC offers a special plugin for Protocol Buffers compiler, which can further compile .proto files to server-side and client-side artifacts for gRPC API services, in addition to the data classes. To use the plugin, you need to add service definitions to your .proto files, which describes your gRPC APIs. Each gRPC API takes one Protocol Buffers message type as input (request), and another Protocol Buffers message type as output (response).

Which technologies should I use?

HTTP RESTful API enjoys great popularity as it works well with virtually every environment: as long as the environment is able to connect to the API endpoint and make an HTTP request, it can use the API service. However, the nature of HTTP/1.1 limits severely the performance of HTTP RESTful APIs: if you plan to stream some media contents, HTTP REST API is hardly a good choice.

gRPC APIs, on the other hand, performs much better than HTTP RESTful APIs in general and offers many additional features, such as streaming and extensible authentication. However, gRPC framework may not work in your target environment, and the platform running your API service might not support incoming gRPC connections.

If you choose to use gRPC for your project, with a little bit of extra effort you might be able to enjoy both the high performance of gRPC APIs and the compatibility of HTTP RESTful APIs. gRPC community offers a gateway solution capable of simultaneously translating standard HTTP RESTful API requests to gRPC requests. With the gRPC Gateway enabled, you can offer support for both HTTP RESTful APIs and gRPC APIs in your service.

What’s next

This series features a collection of guides and tutorials. See below for a list of topics:

• Designing APIs
• Authorization and Authentication in API services

HTTP RESTful APIs w/ OpenAPI

• Building APIs with OpenAPI
• Building APIs with OpenAPI: Continued
• Building APIs with OpenAPI: Authentication (In progress)
• Building APIs with OpenAPI: Versioning (In progress)

gRPC APIs

• Building APIs with gRPC
• Building APIs with gRPC: Continued
• Building APIs with gRPC: Authentication (In progress)
• Building APIs with gRPC: Versioning (In progress)