Programming language: Go

protoxy alternatives and similar packages

Based on the "Server Applications" category

Do you think we are missing an alternative of protoxy or a related project?

Add another 'Server Applications' Package


Welcome to Protoxy 👋

codecov [License: MIT](#)

What is Protoxy?

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 spins up a reverse proxy server that converts the JSON in your request body to the appropriate Protobuf message type. 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
  1. Configure Postman to send requests through the Proxy server. Postman proxy config

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

Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse";
  1. 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"

Using Protobuf in Query String

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}

Handling Multiple Response Message Types

If your API sends multiple response message types, you 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.


👤 Cam Graff

🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

*Note that all licence references and agreements mentioned in the protoxy README section above are relevant to that project's source code only.