gRPC: Top 6 Things that Bite Newbies

Why it’s Awesome

Top 6 Tips

#0. Philosophy

  1. Always Backward Compatible: We’re used to making liberal changes to our code, but once you have customers depending on the APIs being stable, you can’t just update parameters without breaking clients.
  2. WORA (write once, run anywhere): Because it’s polyglot (works in many languages) there may be parts of the proto files (protobufs) that feels a little unnatural for your platform. You need to keep in mind that a client can be anything from python to C++ so the naming and name-spacing rules may not match what you’re used to.
  3. REST vs RPC: Nouns vs Verbs. Lastly, coming from REST you may be thinking in terms of objects and CRUD operations. Going to gRPC is a bit more function oriented (Operation-oriented in gRPC lingua), although it’s still very natural for object-oriented languages. Which brings us to the tips…

#1. OOPs Don’t Worry

  • class => “service”. A set of methods acting on structured data.
  • Functions (and methods) => “rpc
  • struct => “message
  • Arrays [] => “repeated” (e.g. int_32 a[] == repeated int32 a)
  • include (using) => “import
  • union => “oneof
struct HelloRequest {
string name;
};
struct HelloReply {
string message;
};
class Greeter {
public static HelloReply sayHello(HelloRequest request);
};
syntax = "proto3";
// ...
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}

#2. Take and Return Messages

syntax = "proto3";service EchoService {
rpc Echo (string) returns (string);
}
syntax = "proto3";service EchoService {
rpc Echo (EchoRequest) returns (EchoResult);
}
message EchoRequest {
string msg = 1;
}
message EchoResult {
string msg = 1;
}
message EchoResult {
string msg = 1;
int32 status = 2;
}

#3. Same Shape, Different message Please.

#4. Missing or New fields show up with a Default Value

message EchoResult {
string msg = 1;
enum StatusCode {
NONE = 0; // default if missing
SUCCESS = 1;
BAD_INPUT = 2;
}
StatusCode status = 2;
}

#5. How to Rename or Remove fields

message EchoResult {
string msg = 1;
int32 status = 2 [deprecated = true]; // <- Changed
enum StatusCode {
NONE = 0;
SUCCESS = 1;
BAD_INPUT = 2;
}
StatusCode status_code = 3; // <- New name and field #3
}

#6. Remember Polyglot

Other Tips

  • Beware proto2! Many online examples are still proto2, but the Internet goes stale fast. Be sure to learn from proto3 tutorials.
  • Well Known Types: avoid the urge to define a common data types for your set of protos, if you can use one of the “WKT” (well known types) here that includes things like Duration and Timestamp.
  • API vs Storage messages: It’s fine to use protobufs to define APIs and physical storage, but avoid the urge to use a single message. Instead define two separate messages that can evolve on their own.

Conclusion

--

--

--

Roblox, Facebook, Yahoo YST, Distributed Systems, KV & NoSQL, Monitoring, DevOps, CTO, Principal Engineer, etc.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

How You Can Add To And Enhance Your Data Science Portfolio

Using Flow Builder to Update Selected List View Records

Best Low-Code Development Platforms in 2022

Points-To-Consider When Hiring Android Application Developer

Game of Licenses: Facebook vs. Apache

Truecaser

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Charles Thayer

Charles Thayer

Roblox, Facebook, Yahoo YST, Distributed Systems, KV & NoSQL, Monitoring, DevOps, CTO, Principal Engineer, etc.

More from Medium

How I Keep in Touch With My Favorite Programming Communities

UART | Microcontroller Communication With The Terminal

Linux: Software libraries in C

Coding in MS-DOS Batch