Building APIs with OpenAPI

This document discusses how to define a simple, one endpoint HTTP RESTful API service with OpenAPI, and prepare its client-side and server-side code with OpenAPI Generator. It is a part of the Build API Services: A Beginner’s Guide tutorial series.

Note: This tutorial uses Python 3. OpenAPI generator, of course, supports a variety of programming languages.

About the API service

In this tutorial you will build an API service using gRPC where users can get their profiles. It has one resource, User, and one method (endpoint) only:

Before you begin

1. Set up your Python development environment. For this tutorial you do not need to install Google Cloud SDK and Google Cloud Client Library for Python.
2. Install OpenAPI Generator. Alternatively, you can use the online generator.
3. Download the source code. Open /openapi/getting_started.

Understanding the code

Essentially, an API call is nothing but an input (request), an output (response), and some magic that associates the request with the response. Input offers all the parameters the method requires, and output is what the method returns.

In an HTTP RESTful API service, inputs are HTTP requests while outputs are HTTP responses (more specifically, status codes with messages). Inputs and outputs are associated with resources and methods; they specify where and how clients should send the requests and get the responses.

OpenAPI helps developers specify the input/output schemas, the resources and the methods. With an OpenAPI specification, OpenAPI generator can prepare server-end and client-end artifacts (stubs) automatically in the programming language and framework of your choice. You can use these artifacts to easily build your own HTTP RESTful API service and client libraries for the API service.

Resources and their fields

This gRPC API service features one resource: User.

The resource name of User is of the format //myapiservice.com/users/USER-ID. User features 3 fields:

OpenAPI has built-in support for field types. Mark reserved fields with keyword readOnly and required fields required. Fields are optional by default.

Writing OpenAPI specification

YAML file openapi.yaml (openapi/getting_started/openapi.yaml) is the OpenAPI specification of this API service. It comprises 5 parts: openapi, info, servers, components, and paths.

openapi: 3.0.2
info:
  ...
servers:
  ...
components:
  ...
paths:
  ...

openapi

openapi is a string specifying the version number of OpenAPI specification this document uses. For this tutorial you will use Open API Specification Version 3.

info

info is the metadata of the API service:

servers

servers specifies connectivity information of the API service. For this tutorial you will use a local address, localhost:8080.

components

components are a collection of reusable schemas throughout the API service. For this tutorial you will use two schemas, User and ErrorMessage, as the output of the GetUser endpoint.

paths

paths are the resources and methods supported by the API service:

Preparing the code

OpenAPI generator can now prepare server-side and client-side artifacts:

# Prepare the server-end code
openapi-generator generate -i openapi.yaml -g python-flask -o codegen_server/

# Prepare the client-end code
openapi-generator generate -i openapi.yaml -g python -o codegen_client/

Two Python packages now reside in codegen_server and codegen_client. The schemas (User and ErrorMessage) live in the models folder of codegen_server/openapi_server and codegen_client/openapi_client as standard Python classes. controllers in codegen_server/openapi_server specifies how the API service runs; modify the controllers to create your own HTTP RESTful API service. See openapi/getting_started/codegen_server_completed for an example. The default controller (codegen_server_completed/openapi_server/controllers/default_controller.py) looks like this:

Give it a try

To run the API service, change to the directory codegen_server_completed/ and run the following commands:

# Install dependencies for the API service
pip install -r requirements.txt

# Start the API service
python -m openapi_server

Try the API service in browser at localhost:8080/users/1. You should see the following outputs:

{
  "display_name": "Example User",
  "email": "user@example.com",
  "name": "1"
}

OpenAPI Generator also provides a UI for your convenience; visit it at localhost:8080/ui.

If you would like to use the generated client to access the API service, open a new terminal, go back to the directory getting-started/, and install the client as a local dependency:

pip install -e codegen_client/

Then run the following Python script:

import openapi_client
client = openapi_client.DefaultApi()
client.get_user(user_id=’1')

You should see the following outputs:

{‘display_name’: ‘Example User’, ‘email’: ‘user@example.com’, ‘name’: ‘1’}

What’s next

See Building APIs with OpenAPI: Continued for recommended practices and patterns in HTTP RESTful API services.