API Design: Comparing gRPC, OpenAPI, and REST

Posted on Dec 16, 2024 in Computers

Topic 4: API Design

Understanding gRPC, OpenAPI, and REST in API Design

Introduction

• Two primary models for API design: RPC [Procedure] and REST [Entity]
• Most modern APIs map to the HTTP protocol
• RPC API designs often adopt ideas from HTTP
• This presentation explains the choices and provides guidance

gRPC Overview

• gRPC: Technology for implementing RPC APIs using HTTP 2.0
• RPC model: Addressable entities are procedures, data hidden behind procedures
• HTTP model: Addressable entities are data entities (resources), behaviors hidden behind data

Combining RPC and HTTP

• Many APIs combine RPC with HTTP ideas
• Entity-oriented model like HTTP, but defined and implemented using gRPC
• Resulting APIs can be invoked using standard HTTP technologies
• In fact, many of the APIs created at Google and elsewhere combine RPC with a few ideas from HTTP in an interesting way.

Why Combine RPC and HTTP?

• Benefits of combining RPC and HTTP
• Potential drawbacks and considerations

The Three Primary Ways to Use HTTP for APIs

• Most public APIs and many private distributed APIs use HTTP as the transport
• Organizations are accustomed to dealing with the security issues of allowing HTTP traffic on ports 80 and 443

Three Significant Approaches

• REST
• gRPC (and Apache Thrift and others)
• OpenAPI (and its competitors)

REST

• Clients do not construct URLs from other information; they use the URLs passed by the server as-is
• Similar to how browsers work:
  • Browsers do not construct URLs from parts or understand website-specific URL formats
  • Browsers follow URLs found in the current page, bookmarks, or user input
  • Browsers only parse URLs to extract information for HTTP requests and form absolute URLs from relative and base URLs
• In REST APIs, clients do not need to understand URL formats, which are not part of the API specification

Simplicity of REST APIs

• REST APIs can be very simple
• Additional technologies for REST APIs include JSON API, ODATA, HAL, Siren, JSON Hyper-Schema, etc.
• These technologies are not necessary to implement REST effectively

gRPC Overview:

• gRPC is a model for using HTTP for APIs.
• It uses HTTP/2 underneath but hides HTTP from both the API designer and the client/server.
• gRPC-generated stubs and skeletons abstract away the details of how RPC concepts map to HTTP.
• Users only need to learn gRPC, without worrying about HTTP mappings.

Steps to Use a gRPC API:

1. Decide which procedure to call.
2. Calculate the parameter values to use (if any).
3. Use a code-generated stub to make the call, passing the parameter values.

OpenAPI

• Uses specification languages like OpenAPI (formerly known as the Swagger specification)

Signature Characteristic

• Clients use the API by constructing URLs from other information

Steps to Use an OpenAPI API

1. Decide which OpenAPI URL path template to use
2. Calculate the parameter values to use (if any)
3. Plug the parameter values into the URL path template and send an HTTP request

Concept of OpenAPI Paths

• OpenAPI paths define the endpoints of your API.
• Each path corresponds to a specific operation that can be performed.
• Paths are defined in the OpenAPI specification under the ‘paths‘ object.

Examples:

Constructing API Designs

• Define resource paths and methods (GET, POST, etc.).
• Identify input parameters: path parameters, query parameters, etc.
• Structure the responses using appropriate status codes.
• Example: /users path with different HTTP methods.

Step-by-step API Deployment

Deployment Process:

1. Step 1: Write OpenAPI spec in YAML or JSON.
2. Step 2: Validate the API specification using a tool like Swagger Editor.
3. Step 3: Choose a cloud service provider (e.g., AWS API Gateway).
4. Step 4: Deploy the API to the cloud. [Endpoint]
5. Step 5: Set up authentication (optional). [Token Files/JWT]
6. Step 6: Test the API using tools like Postman.

OpenAPI Compared to REST APIs

• OpenAPI method requires clients to have detailed knowledge of URL formats
• Clients construct URLs that conform to the required format
• This is opposite to REST APIs, where clients are blind to URL formats
• OpenAPI model is adopted successfully, despite not being REST

Comparison of OpenAPI and gRPC Client Models

• The client model for using an OpenAPI API is very similar to the client model for using a gRPC API [Procedure Calls]
• gRPC client chooses a procedure to call, OpenAPI client chooses a URL path template to use [Code Generated]
• Both gRPC and OpenAPI clients calculate parameter values
• gRPC client uses a stub procedure to combine parameters with the procedure signature and make the call
• OpenAPI client inserts parameter values into the URL path template and issues an HTTP request [Query String Parameters]
• OpenAPI includes tools to generate a client stub procedure in the client programming language, making the client experience similar to gRPC [Language Binding]

Similarity Explanation

• OpenAPI can be considered a language for specifying a classic RPC API with a custom mapping to HTTP requests
• gRPC and OpenAPI are both RPC interface definition languages (IDLs)
• Essential difference: OpenAPI exposes HTTP transport details to the client, gRPC hides HTTP details using a predefined mapping

RPC API // REST API

Data and Identifiers in API Requests

• The username, contact email, password, account URL, and other data supplied by the client are simple JSON name/value pairs in the request body.
• Details of headers and result formats are explained in the HTTP specifications.
• No choices or decisions are needed for headers and result formats.

Identifiers as URLs

• All identifiers passed between the client and server are URLs.
• No identifiers in the API are non-URLs.
• References between resources are expressed using URLs.
• This technique is called hypertext or hypermedia.
• Hypertext linking is a signature feature of the REST model.
• RPC APIs also express relationships between entities using identifiers, but these are not URLs.

Advantages of REST

• The claimed advantages of REST are similar to those of the world wide web: stability, uniformity, and universality.
• These advantages are documented elsewhere, and REST is a minority interest, so we won’t dwell on them too much here.
• Exception: The entity-orientation inherent in the HTTP/REST model.
• This feature is of special interest and has been widely discussed and adopted by proponents of non-REST models like gRPC and OpenAPI.

Entity-Oriented Models

• Simpler, more regular, easier to understand, and more stable over time than simple RPC models.
• RPC APIs tend to grow organically, adding procedures for each action the system can perform.

Example: Online Shopping

• Entity model includes products, carts, orders, accounts, etc.

Advantages of REST

• The claimed advantages of REST are similar to those of the world wide web: stability, uniformity, and universality.
• The entity-orientation inherent in the HTTP/REST model is of special interest and has been widely discussed and adopted by non-REST models such as gRPC and OpenAPI.

Entity-Oriented Models

• Simpler, more regular, easier to understand, and more stable over time than simple RPC models.
• RPC APIs tend to grow organically, adding procedures for each action the system can perform.

Example: Online Shopping

• Entity model includes products, carts, orders, accounts, etc.
• Using only RPC procedures results in a long, unstructured list of procedures.
• Difficult to achieve coherence between procedure definitions.
• Entity-oriented models provide structure and order by using a standard set of procedures for each entity type.
• HTTP is inherently entity-oriented, but entity-orientation can also be added to RPC.
• Grouping procedures by entity type is a key idea of object-oriented languages.

Path Definitions in APIs [Understanding]

• APIs that define paths expose values like {petId} to the client in various places.
• Clients must use an appropriate path definition to convert {petId} (and other values) into a URL for HTTP requests.
• This method of expressing and using IDs is an alternative to the hypertext link, a signature idea of REST.

OpenAPI Terminology

• Variables in paths are called ”parameters”.
• The combination of a path and an HTTP method is called an ”operation”.
• Similar terminology to RPC systems.
• OpenAPI’s use of URL templates with parameters expresses RPC-like concepts with custom mappings to HTTP.

OpenAPI Advantages and Disadvantages

• OpenAPI has two fundamental characteristics that account for its success:
  • Similarity to the traditional RPC model, familiar and comfortable for most programmers.
  • Allows custom mapping of RPC concepts to HTTP requests.

Advantages

• Clients can access the API using only standard HTTP technologies.
• Important for public APIs as it ensures accessibility from almost all programming languages and environments.
• No need for clients to adopt additional technology.

Disadvantages

• Significant effort required to design the HTTP details.
• Additional effort needed by consumers to learn the API.

Entity-Oriented Approach with gRPC

• To use RPC in an entity-oriented style, reverse the usual RPC thought process.
• Start by defining your resource types.
• Then make RPC method definitions for common entity operations on those types.
• Add any additional operations as necessary.

Constrained Usage Pattern

• In practice, APIs designed this way are sometimes a blend of entity-oriented and procedure-oriented concepts.
• This blending can undermine some of the benefits.

Entity-Oriented Approach with gRPC

• Using an entity-oriented approach with gRPC is mostly useful for new-builds.
• Retrofitting to an existing RPC API is not easy.

Data Update Mechanisms

• gRPC does not define a standard mechanism to prevent data loss during concurrent updates.
• You will likely need to invent your own mechanism.
• HTTP defines standard Etag and If-Match headers for this purpose.
• Most HTTP APIs use these headers.

Entity-Oriented Approach with gRPC

Partial Updates

• gRPC does not define a mechanism for partial updates.
• You will likely need to invent your own mechanism.
• HTTP defines the PATCH method for partial updates but does not specify the patch format.
• Two IETF standards for JSON: JSON merge patch and JSON patch.
• JSON merge patch is simpler but does not handle all cases.
• JSON patch handles more cases but is more complex.
• Recent HTTP APIs often implement both standards and let the client choose.
• The Kubernetes API also works this way.

gRPC Benefits

• gRPC expresses an RPC API in an interface description language (IDL) benefiting from a long tradition of RPC IDLs (e.g. Corba IDL).
• gRPC’s IDL provides a simpler and more direct way of defining remote procedures than OpenAPI’s approach.

HTTP/2 and Simplification

• gRPC uses HTTP/2 but does not expose it to the API designer or user.
• gRPC makes all decisions on layering the RPC model on top of HTTP, simplifying life for API designers and clients.
• OpenAPI requires designers to specify how the RPC model is expressed on top of HTTP, and clients must learn these details.

gRPC Benefits

Client-Side Programming Libraries

• gRPC excels at generating intuitive and efficient client-side programming libraries.
• OpenAPI can also generate client-side libraries, but gRPC’s simplicity is often preferred.

Server-Side Implementation

• gRPC simplifies server-side implementation with frameworks, libraries, and code-generation.
• It may be easier to implement a gRPC method than a standard HTTP request handler.

gRPC Benefits

Performance and Protocol Stability

• gRPC uses efficient binary payloads and HTTP/2 for connection management.
• Avoids the problem of incomplete HTTP protocol implementation in APIs.
• Requires special software for both client and server to implement the complete gRPC protocol.
• Aims for long-term protocol stability similar to HTTP.

Downsides of gRPC

HTTP APIs vs. gRPC

• HTTP APIs can be used and implemented with general-purpose, widely available technologies.
• API calls can be made by typing URLs into a browser or using cURL commands.
• Programmers can access or implement an HTTP API with a basic HTTP library.
• gRPC requires special software on both the client and server.
• gRPC-generated code must be incorporated into client and server build processes.

Downside of gRPC

Crawling and Proxying

• Simple to write a bot to crawl a REST API without metadata.
• Not possible with RPC-style APIs (gRPC or OpenAPI) due to different APIs for each entity type.
• HTTP APIs are often proxied for security, input validation, data format mapping, etc.
• Proxies modify headers and body using standard and custom headers.
• Products like Apigee Edge implement these features without traditional programming skills.
• Proxying for gRPC is harder and less common.

Summary

• Parallels between OpenAPI and gRPC are evident, despite being distinct from REST
• These parallels motivate a more detailed comparison
• Each approach (REST, gRPC, OpenAPI) has benefits and drawbacks
• Explore all three to decide which is best for your application