GolangUK 2017 Talk: Slides and Video
Last month, I got the opportunity to give a talk at the 2017 Golang UK Conference. I'll summarize the content of my talk in this post, and you can find the full video as well as slides below.
How to build SDKs in Go
Lessons from the Go SDK for Dropbox
1. Use a Code Generator
Most of what an SDK does is boilerplate. Be smart, use a code generator! (e.g. Stone). There are two parts to this: defining the API specification (language agnostic), and generating the code (language specific).
2. Avoid Surprises
Think from a user's perspective -- don't do anything that will be surprising or unexpected. Like pulling in external dependencies or even vendored dependencies. If your API has a large surface area, provide scoped sub-packages that users can import!
3. Make Configuration Simple
Your SDK should be configurable, and this configuration should be simple. Don't use command-line flags. Use environment variables with extreme caution. Consider encapsulating all configuration in some struct-type that callers can pass in when initializing the SDK. Let applications handle persistence!
4. Provide Visibility
Have an option for verbose logging and if possible, configurable logging targets.
5. Use Go Idioms for Unsupported Types
Go doesn't support unions. Or true polymorphic inherited types. Or generics. Yet.
Do the best you can within Go idioms. See slides and video for a lot more detail.
6. Do Not Authenticate
Let the application deal with authentication (after all, the app and its developers know what's best for their users and their workflows), the SDK should simply accept a pre-authenticated OAuth token. Note that OAuth in Go has other idiosyncracies to watch out for. One example is at On debugging OAuth2 in #golang
7. Auto Generate Tests
Since we're generating code anyways, might as well extend that to tests. This is especially useful for coverage across multiple languages.
8. Handle Errors the Go Way
Make sure any custom error types implement the error interface and leverage type assertions to extract SDK-specific error information.