[Documentation] Use protocurl to interact with twirp protobuf endpoint instead of curl+protoc

[GollyTicker]

Hi everyone,

I want to discuss a minor suggestion in the documentation - which Is why I first created this issue instead of directly creating a pull request with the documentation changes.

This section in the documentation explains how one can send simple requests against a twirp protobuf endpoint using a combination of curl and protoc. While it works, it seems slightly cumbersome as a command line experience.

To make life easier, I've created the open-source command line tool protoCURL. This CLI adds some convinience whlie enabling one to write JSON or Protobuf Text Format when interacting with a Protobuf HTTP REST endpoint.

The example from the docs

echo 'subject:"World"' \
    | protoc --encode example.helloworld.HelloReq ./rpc/helloworld/service.proto \
    | curl -s --request POST \
      --header "Content-Type: application/protobuf" \
      --data-binary @- \
      http://localhost:8080/twirp/example.helloworld.HelloWorld/Hello \
    | protoc --decode example.helloworld.HelloResp ./rpc/haberdasher/service.proto

would then be written instead as

protocurl -I rpc/helloworld -i ..HelloReq -o ..HelloResp \
  -u http://localhost:8080/twirp/example.helloworld.HelloWorld/Hello \
  -d 'subject:"World"' -q

The second form is smaller and easier to work with - which is also the reason why I created the CLI. It handles the protobuf conversions while allowing one to write directly in the protobuf text format / JSON. It goes through the messages in the proto files directory and searches for the (unique) message type definitions given the paths ..HelloReq and ..HelloResp (where .. stands for "please infer the full path for me"). You can find more examples of the CLI usage here.

What do you think? Perhaps it could make sense, to add-to/replace the way of interacting with the twrip endpoints to the docs?

Disclaimer: I have not used Twirp in any project - but while looking for solutions to this problem (before creating protocurl) - I had found your documentation. Since there is a solution for this exact problem, you might be interested in integrating it.

Thanks for your attention!

[dongyeopdukelee]

Hi, thanks for your efforts to make the documentation better. We discussed this and decided to not add protocurl into Twirp or its documentation to keep the library more accessible. While protocurl simplifies the command, it also obfuscates some of the important details within the command unless the reader dives into protocurl documentation.

[GollyTicker]

All right. Thanks for the transparent communication!