Kyle Conroy Gray

The humble API client. A deceptively simple piece of software. Make a request and parse a response. Repeat.

With the rise of public web services, API clients have become the main integration point. However, many of the Go clients I encounter are obtuse. Here's my guide for writing boring API clients that age well.

We'll use the Dropbox Paper API as our example. First, start with a client struct.

type client struct {
    // unexported fields
}

Each API method should be represented as an exported method on the client. We'll use the document download method as our example.

func (c *client) DownloadDoc() {}

The method should have two arguments: a context and a method-specific argument struct. It may feel awkward passing around structs instead of positional arguments, but structs allow you to make additions to methods without making breaking changes to the methods signatures.

type DocExport struct {
    DocID  string
    Format ExportFormat
}

func (c *client) DownloadDoc(ctx context.Context,
    in *DocExport) {
    // implemetation
}

Take special care in avoiding stringly-typed APIs. If a struct field is limited to a set of values, create a new type that encapsulates those values. In this case, the Format field can only have two values: markdown and html.

type ExportFormat string
const (
    ExportFormatMarkdown ExportFormat = "markdown"
    ExportFormatHTML                  = "html"
)

As an added bonus, these types work natively with the encoding/json package.

The method should return two results: a method-specific return value struct and an error.

type DocExportResult struct {
    Owner    string
    Title    string
    Revision int64
    MIME     string
    Content  []byte
}

func (c *client) DownloadDoc(ctx context.Context,
    in *DocExport) (*DocExportResult, error) {
    // implemetation
}

You may have noticed that our client struct isn't exported. Instead of exporting your concrete type, export an interface. Using an interface makes it easier for downstream consumers to mock out calls to your package.

type Client interface {
    DownloadDoc(context.Context, *DocExport) (
        *DocExportResult, error)
}

For increased flexibility, allow users to pass in their own http.Client, as many use cases require a customized HTTP transport.

func NewClient(token string, hclient *http.Client) Client {
    // implementation
}

This isn't the only way to design API clients in Go. Have another style you like more? I'd love to know about it.