Have you ever left out a comma in your payload calling an API on the command line? Have you cURL’d a REST API only to realize you forgot that crucial query parameter? If only the command line could take advantage of some structured description of the API model…
APIs can be challenging to understand and consume from the command line, a utility most developers use daily. In this session we will look at an approach to generating intuitive command line utilities for gRPC APIs.
12. Protocol Buffers
IDL (Interface definition language)
Describe once and generate interfaces for any
language.
Data Model
Structure of the request and response.
Wire Format
Binary format for network transmission.
service RouteGuide {
rpc GetFeature(Point) returns (Feature);
rpc RouteChat(stream RouteNote) returns (stream RouteNote);
}
message Point {
int32 latitude = 1;
int32 longitude = 2;
}
message Feature {
string name = 1;
Point location = 2;
}
message RouteNote {
Point location = 1;
string message = 2;
}
13. C/C++
Java is a registered trademark of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
15. State of the Art
● Server reflection-based CLIs
○ Similar to HTTP cURL
○ Favors flexibility over API
consumption experience
● github.com/grpc/grpc/.../grpc_cli
● github.com/fullstorydev/grpcurl
#grpcurl example
# listing available Services
> grpcurl my.api.net list
MyService
# listing Service RPCs
> grpccurl my.api.net list MyService
MethodA
MethodB
# describing specific Service RPC
> grpcurl my.api.net describe MyService MethodA
…
# describing specific Message
> grpcurl my.api.net describe MethodAInput
…
# invoking a Service RPC
> grpcurl -d '{"name": "Jane Doe"}'
my.api.net
MyService.MethodA
…
22. Generated Command Line Interfaces (gcli)
● Go lang
● Cobra CLI framework
● Uses Google generated API clients (GAPIC)
● github.com/googleapis/gapic-generator-go
23. Goals
● Generate a CLI tailored to a given gRPC
API
● Generate a more human-oriented
interface
● Unified experience across consumption
mediums
Non-Goals
● Provide a single, generic utility that can
invoke any gRPC API
● Replace gcloud SDK as the canonical
Google Cloud CLI
28. kctl ... --kiosk_ids=<int32> --kiosk_ids=<int32>
Repeated field name Repeated field type
Payload construction: Repeated Primitives
29. kctl ... --size.width=<int32> --size.height=<int32>
Nested
field’s
name
Nested
message
field
name
Nested
message
field
type
Payload construction: Nested Messages
35. Educate the consumer: --help
$ kctl display create-sign --help
Create a sign. This enrolls the sign for sign display.
Usage:
kctl display create-sign [flags]
Flags:
--from_file string Absolute path to JSON file containing request payload
-h, --help help for create-sign
--image bytesHex Data of image currently displayed on sign
--name string Required. Name of the sign
--text string Text to display on sign
...
36. Educate the consumer: bash autocompletion
$ kctl completion --help
Enable bash completion like so:
Linux:
source <(kctl completion)
Mac:
brew install bash-completion
kctl completion > $(brew --prefix)/etc/bash_completion.d/kctl
Usage:
kctl completion [flags]
Flags:
-h, --help help for completion
43. Wrapping it up
● CLI API consumption is a gateway & important tool
● Structured API definitions should guide the CLI experience
● Educate the consumer at every opportunity
● Not every API is meant for the command line