Transcoding reference

Review examples for how to annotate your proto files to add HTTP mappings. These HTTP mappings are used by Gloo Gateway to transcode HTTP/ JSON requests to gRPC requests so that they can be forwarded to your gRPC upstream. The examples in this doc are based on the Bookstore app that you deploy as part of the Transcode HTTP requests to gRPC guide.

To find more examples for how to add HTTP mappings to proto files and their syntax, refer to Transcoding HTTP/JSON to gRPC in the Google Cloud documentation.

On this page:

Map a List method

The List method is typically used to retrieve or search for a list of resources.

HTTP mapping rules

Example for getting a list of all resources

rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
    option (google.api.http) = {
      get: "/shelves"
    };
  }
  
message ListShelvesResponse {
  // Shelves in the bookstore.
  repeated Shelf shelves = 1;
}

In this example:

The code example implements the following HTTP to gRPC transcoding.

HTTP gRPC
curl -X GET http://{$DOMAIN_NAME}/shelves ListShelves()

Map a Get method

The Get method is typically used to retrieve a specific resource.

HTTP mapping rules

Example without query parameters

rpc GetAuthor(GetAuthorRequest) returns (Author) {
    option (google.api.http) = {
      get: "/authors/{author}"
    };
  }
  
message GetAuthorRequest {
  // The ID of the author resource to retrieve.
  int64 author = 1;
}

message Author {
  // A unique author id.
  int64 id = 1;
  enum Gender {
    UNKNOWN = 0;
    MALE = 1;
    FEMALE = 2;
  };
  Gender gender = 2;
  string first_name = 3;
  string last_name = 4 [json_name = "lname"];
}

In this example:

The code example implements the following HTTP to gRPC transcoding.

HTTP gRPC
curl -X GET http://{$DOMAIN_NAME}/authors/1 GetAuthor(author: "1")

Map a Create method

The Create method is typically used to create a new resource under a specified parent. The newly created resource is then returned to the client.

HTTP mapping rules

Example to create a resource

rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
    option (google.api.http) = {
      post: "/shelf"
      body: "shelf"
    };
  }
  
message CreateShelfRequest {
  // The shelf resource to create.
  Shelf shelf = 1;
}
  
message Shelf {
  // A unique shelf id.
  int64 id = 1;
  // A theme of the shelf (fiction, poetry, etc).
  string theme = 2;
}

In this example

The code example implements the following HTTP to gRPC transcoding.

HTTP gRPC
curl -X POST http://{$DOMAIN_NAME}/shelf -d {"id":"1234","theme":"drama"} CreateShelf(id: "1234" theme: "drama")

Example to create a resource with HTTP PUT

rpc CreateBook(CreateBookRequest) returns (Book) {
    option (google.api.http) = {
      put: "/shelves/{shelf}/books"
      body: "book"
    };
  }
  
message CreateBookRequest {
  // The ID of the shelf on which to create a book.
  int64 shelf = 1;
  // A book resource to create on the shelf.
  Book book = 2;
}

message Book {
  // A unique book id.
  int64 id = 1;
  // An author of the book.
  string author = 2;
  // A book title.
  string title = 3;
  // Quotes from the book.
  repeated string quotes = 4;
}

In this example:

The code example implements the following HTTP to gRPC transcoding.

HTTP gRPC
curl -X PUT http://{$DOMAIN_NAME}/shelves/1/books -d {"id":"50","author":"12345", "title": "The long ride"} CreateBook(shelf: "1" book: Book(id: "50" author: "1234" title: "The long ride"))

Map an Update method

The Update method is typically used to update the properties for a specific resource. After the resource is updated, it is returned to the client.

HTTP mapping rules

Example for updating a resource

rpc UpdateBook(UpdateBookRequest) returns (Book) {
    option (google.api.http) = {
      patch: "/shelves/{shelf}/books/{book.id}"
      body: "book"
    };
  }

message UpdateBookRequest {
  // The ID of the shelf from which to retrieve a book.
  int64 shelf = 1;
  // A book resource to update on the shelf.
  Book book = 2;
}

message Book {
  // A unique book id.
  int64 id = 1;
  // An author of the book.
  string author = 2;
  // A book title.
  string title = 3;
  // Quotes from the book.
  repeated string quotes = 4;
}

In this example:

The code example implements the following HTTP to gRPC transcoding.

HTTP gRPC
curl -X PATCH http://{$DOMAIN_NAME}/shelves/1/books/2 -d {"id":"2","author":"57", "title": "The last ride"} UpdateBook(shelf: "1" book: Book(id: "2" author: "57" title: "The last ride"))

Map a Delete method

The Delete method is used to delete a specific resource.

HTTP mapping rules

Example for deleting a resource

rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/shelves/{shelf}/books/{book}"
    };
  }
  
message DeleteBookRequest {
  // The ID of the shelf from which to delete a book.
  int64 shelf = 1;
  // The ID of the book to delete.
  int64 book = 2;
}

In this example:

The code example implements the following HTTP to gRPC transcoding.

HTTP gRPC
curl -X DELETE http://{$DOMAIN_NAME}/shelves/1/books/2 DeleteBook(shelf: "1" book: "2")