api

API

This package contains API artifacts such as protobuf annotations.

Protobuf Usage

1. Define your gRPC service using protocol buffers

   your_service.proto:

   syntax = "proto3";
   package example;
   message StringMessage {
     string value = 1;
   }
   
   service YourService {
     rpc Echo(StringMessage) returns (StringMessage) {}
   }
   

2. Add a semaphore.api annotation to your .proto file

   your_service.proto:

    syntax = "proto3";
    package example;
   +
   +import "semaphore/api/annotations.proto";
   +
    message StringMessage {
      string value = 1;
    }
   
    service YourService {
   +  option (semaphore.api.service) = {
   +    host: "127.0.0.1:80"
   +    transport: "http"
   +    codec: "json"
   +  };
   +
   -  rpc Echo(StringMessage) returns (StringMessage) {}
   +  rpc Echo(StringMessage) returns (StringMessage) {
   +    option (semaphore.api.http) = {
   +      post: "/v1/example/echo"
   +      body: "*"
   +    };
   +  }
    }
   

   You will need to provide the required third party protobuf files to the protoc compiler. They are included in this repo under the api folder, and we recommend copying them into your protoc generation file structure. If you've structured your protofiles according to something like the Buf style guide, you could copy the files into a top-level ./semaphore folder.

   If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external Service Configuration file. Check our documentation for more information.

3. Write flow your definitions as usual