Building API Services: A Beginner’s Guide (2024)

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.

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.

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.