Building Microservices with Go

RPC based-based APIs

With RPC APIs there is an argument that your contract is your documentation, in the following example we define the interface using the protocol buffers DSL and would make any necessary comments to assist the consumer as required. The predominant theory to follow is one of self-documenting code that your methods and parameter names should infer intent and enough description to negate the use of comments.

Protocol buffer example:

// The greeting service definition. service Users {   // Create user creates a user in the system with the given User details,   // it returns an Error message which will be nil on a successful operation   rpc CreateUser (User) returns (Error) {} } // Person describes a user entity message User { ...