For a while, the whole world was trying to move over from REST to GraphQL. Frontend developers loved it because they could get exactly what they wanted. However, implementing a backend for it is a lot of work. So, when I saw a blog post criticizing GraphQL, it resonated with me.

REST is simple and easy to use. However, maintaining the REST schema is always involved.

Here’s where the Open API specification comes in. It adds a layer of objects to define the RESTful API.

For internal usage, I think you should start with a server first.

Let’s consider a simple example in Python.

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Save the file below as simple_web_server.py
import dataclasses

from typing import Union
from fastapi import FastAPI

app = FastAPI()


@dataclasses.dataclass
class Response:
  number: int
  square: int


@app.get("/square/{number}")
def read_item(number: int) -> Response:
    return Response(number=number, square=number * number)

Run the file with python -m fastapi dev simple_web_server.py and then see the specification at http://127.0.0.1:8000/openapi.json. You can also see the documentation at http://127.0.0.1:8000/docs.

One can use an online service like readme.io to generate documentation from the specification. Or one can use the API specification to generate the client code.

Let’s say you want to generate the Go client code.

Bash
1
2
3

$ go get github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen
$ go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -generate types,client,spec -o web_server_client.gen.go -package main http://127.0.0.1:8000/openapi.json
...

You can then use the client code to make the API calls.

Go
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

package main

import (
	"context"
	"fmt"
)

// go mod init example && go mod tidy  # One time
// go run go_client.go web_server_client.gen.go  # To run this
func main() {
	num := 10
	sq, err := getSquare(context.Background(), num)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Square of %d is %d\n", num, *sq)
}

func getSquare(ctx context.Context, num int) (*int, error) {
	apiClient, err := NewClientWithResponses("http://127.0.0.1:8000")
	if err != nil {
		return nil, err
	}

	resp, err := apiClient.ReadItemSquareNumberGetWithResponse(ctx, num)
	if err != nil {
		return nil, err
	}

	return &resp.JSON200.Square, nil
}

Commit Open API specification to version control

I would highly recommend against committing the generated code to a version control though.

This way, you can add a vacuum linter to ensure that the specification does not have any errors or lint issues.

Further, use oasdiff in your version control to prevent any breaking changes to the API.

You can use gabo to auto-generate the GitHub Actions to lint, validate, and prevent breaking changes to the Open API specification.