Protocol Buffers Principles

proto.md

Protocol Buffers Structures

syntax = "proto3";
option go_package = "github.com/Ja7ad/bookstore";

service Greeter {
  rpc GetBook(GetBookRequest) returns (Book) {}
  rpc AddBook(AddBookRequest) returns (Book) {}
  rpc AddManyBook(AddManyBookRequest) returns (google.protobuf.Empty) {}
  rpc UpdateBook(UpdateBookRequest) returns (Book) {}
  rpc DeleteBook(DeleteBookRequest) returns(google.protobuf.Empty) {}
}

message Book {
  string id = 1;
  string name = 2;
  BookType type = 3;
  string publisher = 4;
  string published_date = 5;
  int32 pages = 6;
  string language = 7;
}

message AddBookRequest {
  string name = 1;
  BookType type = 2;
  string publisher = 3;
  string published_date = 4;
  int32 pages = 5;
  string language = 6;
}

message AddManyBookRequest {
  repeated AddBookRequest books = 1;
}

message UpdateBookRequest {
  string name = 1;
  BookType type = 2;
  string publisher = 3;
  string published_date = 4;
  int32 pages = 5;
  string language = 6;
}

message DeleteBookRequest {
  string id = 1;
}

message GetBookRequest {
  string id = 1;
}

enum BookType {
  CLASSIC = 0;
  FANTASY = 1;
  HORROR = 2;
}

Naming conventions

• Camelcase names should be used for message names
• You should name your message based on the type of structure and concise (example: book, car, contact, etc.).
• Types of RPC requests and responses should follow (BookRequest / BookResponse)
• The name of the RPC should be AddBook, UpdateBook, DeleteBook, etc.
• RPC requests and responses for multiple should be named AddManyBook, DeleteManyBook and etc. respectively
• All message fields should be lowercase, with words separated by underscores (example published_date, etc.). 
• It is better to name enum fields in uppercase with words separated by underscores

Assigning Field Numbers

message Book {
         string id = 1;
          string name = 2;
          BookType type = 3;
          string publisher = 4;
          string published_date = 5;
          int32 pages = 6;
          string language = 7;
}

each field in the message definition has a unique number. These numbers are used to identify your fields in the message binary format, and should not be changed once your message type is in use, bytes are allocated to each number based on the number range:

• 1-15 take 1 byte
• 16-2048 take 2 byte

Rules

• The smallest field number you can specify is 1
• You also cannot use the numbers 19000 through 19999
• you cannot use any previously reserved field numbers

Specifying Field Rules

• required: a well-formed message must have exactly one of this field.
• optional: a well-formed message can have zero or one of this field (but not more than one).
• repeated: this field can be repeated any number of times (including zero) in a well-formed message (used repeated for array)

Enumerations

Use enumerations for some fields, such as status, type, etc.

Some Techniques for Performance in Protocol Buffers

• sint32 this more efficiently encodes negative numbers than regular int32s.
• Separate messages are better than nested messages
• Instead, use multiple fields use  “oneof” feature