Defining the Service

Let’s start with the header.

The proto-definition starts with this:

syntax = "proto3";

import "google/api/annotations.proto";

package sfapi.v1;
option go_package = "proto";

This clearly marks what version of proto we are using (proto3, so all fields are optional) and prepares the loader for HTTP annotations (used by grpc-gateway, among others) and gives our API a namespace sfapi.v1.

Nouns

We start with a proto description of or nouns. Here is an example for Film:

message Film {
  string title = 1;
  int32 episode_id = 2;
  string opening_crawl = 3;
  string director = 4;
  string producer = 5;
  string release_date = 6;
  repeated string character_ids = 7; // Person.id
  repeated string planet_ids = 8;    // Planet.id 
  repeated string starship_ids = 9;  // Starship.id
  repeated string vehicle_ids = 10;  // Vehicle.id
  repeated string species_ids = 11;  // Species.id
  string id = 12;
}

Verbs

Now, we need our List...