api

API

This directory contains the API specification and all files necessary to build API artifacts. API definitions use gRPC tools for consistent and quality tooling. Within the oracles (middleware), we use grpc-gateway to expose a REST/JSON API (documented in the swagger file) that is transcoded to a gRPC service that is consumed internally.

Entity types and endpoints are defined in protobuf and gRPC. This has several advantages over editing the swagger file directly, including:

• Clean diffs.
• Better backwards compatibilty through field numbers.
• Clear semantics for objects and repeated fields.

Directory Structure

pb:
	Protobuf speciations for entities, models, and messages used and referenced
	in various API endpoints.
srvpb:
	Endpoint specifications (in gRPC format with HTTP/swagger annotations).
swagger:
	Generated swagger JSON and a Go package that serves the json to frontend
	clients.

Generating gRPC service code and Swagger/OpenAPI documentation

The generated gRPC service code, gateway code, and the swagger file are checked into git. After every change you should regenerate these files and check them in. Run make in the api directory to regenerate these files.

make

Among the generated output is a swagger file, swagger/oracle.swagger.json. Do not edit this file directly or it will be replaced the next time any .proto files are modifieed.

Viewing REST API documentation

Use your favorite OpenAPI/Swagger tool to view the swagger file generated above at swagger/oracle.swagger.json. One such tool is redoc. To view the swagger file using redoc, you need to install the CLI first:

brew install npm
npm i -g redoc-cli

Run make redoc at the root of the project to view the User API spec. The port has been set to not conflict with Oracle. You can also run redoc directly:

npx redoc-cli serve -p 57505 ./api/swagger/oracle.swagger.json

Use the swagger editor to view the swagger specification online.