Protoxy allows you to test your REST APIs that use Protocol Buffer serialization through Postman and other API testing tools which do not natively support Protobuf encoding. Protoxy is a proxy server that converts the JSON in your request body to the appropriate Protobuf message type and transforms the response from your back-end back into JSON. You don't need to make any changes to your source code to use Protoxy.

go get github.com/camgraff/protoxy

Consider a proto file located at ./protos/example.proto that looks like this:

syntax = "proto3";
package example;

message ExampleRequest {
    string text = 1;
    int32 number = 2;
    repeated string list = 3;
}

message ExampleResponse {
    string text = 1;
}

1. Start the server by specifying your import paths, proto file names, and optional port.

   protoxy -I ./protos/ --port 7777 example.proto
   

2. Configure Postman to send requests through the Proxy server.

3. Add your fully-qualified message names as params in the Content-Type header.

   Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse";
   

4. Send your request as a raw JSON body.

   {
     "text": "some text",
     "number": 123,
     "list": ["this", "is", "a", "list"]
   }
   

   The response is:

   {
     "text": "this response was automagically converted to JSON"
   }
   

Protoxy also supports sending protobuf messages as a base64 encoded query string in the URL. To do this, add an additional param qs in the header whose value corresponds to the query string parameter. For example:

Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse"; qs="proto_body";

This will result in a URL like:

http://example.com?proto_body={base64 encoding of example.ExampleRequest}

If your API sends multiple response message types, the respMsg parameter accepts a comma-seperated list of values.

Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse,example.DifferentResponse";

Note: Protoxy will attempt to unmarshal your proto messages into each type of response and will send the first successful one. This can produce unexpected results because the same wire-format message can successfully be unmarshalled into multiple proto message types depending on the fields in the proto message. If possible, it is best to ensure that you back-end server returns only one response type per route.

👤 Cam Graff

• Github: @camgraff
• LinkedIn: @camgraff

Contributions, issues and feature requests are welcome!

Feel free to check issues page.

Give a ⭐️ if this project helped you!