api/

API definitions

.
├── *.proto                     # gRPC service definitions
├── buf.gen.yaml                # buf plugins config
├── buf.yaml                    # buf dependecies
├── http.yaml                   # mapping gRPC->HTTP endpoints
├── gen                         # autogenerated:
│   └── grpc
│       └── go
│           ├── *.pb.go         # generated go gRPC clients
│           ├── *_grpc.pb.go    # generated go gRPC server endpoints stubs
│           └── *.pb.gw.go      # generated go HTTP wrappers for gRPC server endpoints
└── openapi
    └── ceph-api.swagger.json   # genrated openapi spec

How to add new endpoint

.proto files from api/ directory are the single source of truth for API definition.

1. To add new endpoint to existing service edit corresponding proto file, or add a new proto file with a new service definition.
2. To generate REST endpoint for defined rpc method, add mapping to api/http.yaml. GRPC gateway library is used to generate and serve REST API from gRPC.
3. Run buf command from api/ directory:

   cd ./api
   buf generate
   

   The command will generate: go code stubs for gRPC and HTTP endpoints and go gRPC client in api/gen/grpc/go/, and openapi spec in api/openapi/
4. Implement go stub for API handler in pkg/api/
5. In case of introducing new gRPC service (not adding new endpoint to existing service), register it in pkg/api/grpc_server.go and http handlers in pkg/api/grpc_http_gateway.go