Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/camgraff/protoxy
A proxy server than converts JSON request bodies to protocol buffers
https://github.com/camgraff/protoxy
go golang postman protobuf protocol-buffers rest rest-api
Last synced: about 2 months ago
JSON representation
A proxy server than converts JSON request bodies to protocol buffers
- Host: GitHub
- URL: https://github.com/camgraff/protoxy
- Owner: camgraff
- License: mit
- Created: 2020-09-03T23:24:34.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-11-08T21:25:43.000Z (about 4 years ago)
- Last Synced: 2024-07-31T20:52:54.626Z (4 months ago)
- Topics: go, golang, postman, protobuf, protocol-buffers, rest, rest-api
- Language: Go
- Homepage:
- Size: 111 KB
- Stars: 35
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - protoxy - A proxy server that converts JSON request bodies to Protocol Buffers. (Server Applications / HTTP Clients)
- zero-alloc-awesome-go - protoxy - A proxy server that converts JSON request bodies to Protocol Buffers. (Server Applications / HTTP Clients)
- awesome-go-extra - protoxy - 09-03T23:24:34Z|2020-11-08T21:25:43Z| (Server Applications / HTTP Clients)
README
# Welcome to Protoxy 👋
[](https://codecov.io/gh/camgraff/protoxy)
[](https://goreportcard.com/report/github.com/camgraff/protoxy)
[](#)
## What is Protoxy?
Protoxy allows you to test your REST APIs that use [Protocol Buffer](https://developers.google.com/protocol-buffers) 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.
## Install
```
go get github.com/camgraff/protoxy
```
## Usage
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"
}
```
### 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, 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.
## Author
👤 **Cam Graff**
* Github: [@camgraff](https://github.com/camgraff)
* LinkedIn: [@camgraff](https://linkedin.com/in/camgraff)
## 🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/camgraff/protoxy/issues).
## Show your support
Give a ⭐️ if this project helped you!
***