Build SDK Quickly with Req


Using the powerful and flexible features of req, we can quickly develop a useful golang SDK for the API provided by the server.

The general idea is:

  1. Embed the Client of req into the struct of the SDK core, and set common properties for all API requests(header, authentication information, base URL, etc).
  2. Extract some general processing logic and register it into the response middleware for handle the response (handle unexpected status codes or API errors).
  3. Integrate the powerful API Debug capability of req into the SDK, and you can dynamically decide whether to enable Debug in the program using the SDK.
  4. In the implementation method of the API, you only need to set the required parameters and the object that will be unmarshalled according to the API, and then return directly. Generally, only a few lines of code are required.

This article takes GitHub API as an example to develop a simple and powerful SDK.

Example for Developing GitHub SDK

Define a Client for GitHub, use req to encapsulate, client.go:

import (

// GithubClient is the go client for GitHub API.
type GithubClient struct {
	isLogged bool

// NewGithubClient create a GitHub client.
func NewGithubClient() *GithubClient {
	c := req.C().
		// All GitHub API requests need this header.
		SetCommonHeader("Accept", "application/vnd.github.v3+json").
		// All GitHub API requests use the same base URL.
		// Enable dump at the request level for each request, which dump content into
		// memory (not print to stdout), we can record dump content only when unexpected
		// exception occurs, it is helpful to troubleshoot problems in production.
		// Unmarshal all GitHub error response into struct.
		// Handle common exceptions in response middleware.
		OnAfterResponse(func(client *req.Client, resp *req.Response) error {
			if resp.Err != nil { // There is an underlying error, e.g. network error or unmarshal error.
				return nil
			if apiErr, ok := resp.ErrorResult().(*APIError); ok {
				// Server returns an error message, convert it to human-readable go error.
				resp.Err = apiErr
				return nil
			// Corner case: neither an error state response nor a success state response,
			// dump content to help troubleshoot.
			if !resp.IsSuccessState() {
				return fmt.Errorf("bad response, raw dump:\n%s", resp.Dump())
			return nil

	return &GithubClient{
		Client: c,

// APIError represents the error message that GitHub API returns.
// GitHub API doc:
type APIError struct {
	Message          string `json:"message"`
	DocumentationUrl string `json:"documentation_url,omitempty"`
	Errors           []struct {
		Resource string `json:"resource"`
		Field    string `json:"field"`
		Code     string `json:"code"`
	} `json:"errors,omitempty"`

// Error convert APIError to a human readable error and return.
func (e *APIError) Error() string {
	msg := fmt.Sprintf("API error: %s", e.Message)
	if e.DocumentationUrl != "" {
		return fmt.Sprintf("%s (see doc %s)", msg, e.DocumentationUrl)
	if len(e.Errors) == 0 {
		return msg
	errs := []string{}
	for _, err := range e.Errors {
		errs = append(errs, fmt.Sprintf("resource:%s field:%s code:%s", err.Resource, err.Field, err.Code))
	return fmt.Sprintf("%s (%s)", msg, strings.Join(errs, " | "))

// LoginWithToken login with GitHub personal access token.
// GitHub API doc:
func (c *GithubClient) LoginWithToken(token string) *GithubClient {
	c.SetCommonHeader("Authorization", "token "+token)
	c.isLogged = true
	return c

// IsLogged return true is user is logged in, otherwise false.
func (c *GithubClient) IsLogged() bool {
	return c.isLogged

// SetDebug enable debug if set to true, disable debug if set to false.
func (c *GithubClient) SetDebug(enable bool) *GithubClient {
	if enable {
	} else {
	return c

Encapsulate APIs for user profile, user_profile.go:

import (

// GetMyProfile return the user profile of current authenticated user.
// Github API doc:
func (c *GithubClient) GetMyProfile(ctx context.Context) (user *UserProfile, err error) {
	err = c.Get("/user").

// GetUserProfile return the user profile of specified username.
// Github API doc:
func (c *GithubClient) GetUserProfile(ctx context.Context, username string) (user *UserProfile, err error) {
		SetPathParam("username", username).

type UserProfile struct {
	Login             string    `json:"login"`
	Id                int       `json:"id"`
	NodeId            string    `json:"node_id"`
	AvatarUrl         string    `json:"avatar_url"`
	GravatarId        string    `json:"gravatar_id"`
	Url               string    `json:"url"`
	HtmlUrl           string    `json:"html_url"`
	FollowersUrl      string    `json:"followers_url"`
	FollowingUrl      string    `json:"following_url"`
	GistsUrl          string    `json:"gists_url"`
	StarredUrl        string    `json:"starred_url"`
	SubscriptionsUrl  string    `json:"subscriptions_url"`
	OrganizationsUrl  string    `json:"organizations_url"`
	ReposUrl          string    `json:"repos_url"`
	EventsUrl         string    `json:"events_url"`
	ReceivedEventsUrl string    `json:"received_events_url"`
	Type              string    `json:"type"`
	SiteAdmin         bool      `json:"site_admin"`
	Name              string    `json:"name"`
	Company           string    `json:"company"`
	Blog              string    `json:"blog"`
	Location          string    `json:"location"`
	Email             string    `json:"email"`
	Hireable          bool      `json:"hireable"`
	Bio               string    `json:"bio"`
	TwitterUsername   string    `json:"twitter_username"`
	PublicRepos       int       `json:"public_repos"`
	PublicGists       int       `json:"public_gists"`
	Followers         int       `json:"followers"`
	Following         int       `json:"following"`
	CreatedAt         time.Time `json:"created_at"`
	UpdatedAt         time.Time `json:"updated_at"`

Well, a simple and powerful GitHub SDK is developed. Only two APIs is implemented, but the implementation function of each API only needs a few lines of code, and other APIs can be quickly encapsulated in the same way.

Next we use the SDK to write a simple executable program:

  1. When a GitHub username is passed to the program, it means to query the user’s information.
  2. When the TOKEN environment variable is set, it means logging in to GitHub and querying the information of the currently logged in user.
  3. When the DEBUG environment variable is set to on, Debug is enabled and the request details are printed.


import (

var github = NewGithubClient()

func init() {
	if os.Getenv("DEBUG") == "on" {
	if token := os.Getenv("TOKEN"); token != "" {

func main() {
	if len(os.Args) > 1 {
		username := os.Args[1]
		user, err := github.GetUserProfile(nil, username)
		if err != nil {
		fmt.Printf("%s's website: %s\n", user.Name, user.Blog)
	if github.IsLogged() {
		user, err := github.GetMyProfile(nil)
		if err != nil {
		fmt.Printf("%s's website: %s\n", user.Name, user.Blog)
	fmt.Println("please give an username or set TOKEN env")

Build and run:

$ go build -o test
$ ./test spf13
Steve Francia's website:

Provide the wrong TOKEN to run:

$ export TOKEN=test
$ ./test
API error: Bad credentials (see doc

Provide the right TOKEN to run:

$ export TOKEN=ghp_Bi6T*****************************ai3
$ ./test
roc's website:

Provide a username that does not exist and run:

$ ./test 683d977eb7854a43
API error: Not Found (see doc

Enable debug and run:

$ export DEBUG=on
$ ./test
2022/05/26 21:26:46.485766 DEBUG [req] HTTP/2 GET
:method: GET
:path: /user
:scheme: https
accept: application/vnd.github.v3+json
authorization: token ghp_Bi6T*****************************ai3
accept-encoding: gzip
user-agent: req/v3 (

:status: 200
date: Thu, 26 May 2022 13:26:46 GMT
content-type: application/json; charset=utf-8
cache-control: private, max-age=60, s-maxage=60
vary: Accept, Authorization, Cookie, X-GitHub-OTP
etag: W/"8b43712c00d18ff0f692b0330329e5c4b4690b3ecd088a5603f1e699cadfc039"
last-modified: Tue, 03 May 2022 12:12:52 GMT
x-oauth-scopes: admin:enterprise, admin:gpg_key, admin:org, admin:org_hook, admin:public_key, admin:repo_hook, delete:packages, delete_repo, gist, notifications, repo, user, workflow, write:discussion, write:packages
github-authentication-token-expiration: 2022-06-25 09:33:01 UTC
x-github-media-type: github.v3; format=json
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4992
x-ratelimit-reset: 1653572352
x-ratelimit-used: 8
x-ratelimit-resource: core
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transportWrapper-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
vary: Accept-Encoding, Accept, X-Requested-With
content-encoding: gzip
x-github-request-id: 42FE:77A0:7826:8159:628F8016

{"login":"imroc","id":7448852,"node_id":"MDQ6VXNlcjc0NDg4NTI=","avatar_url":"","gravatar_id":"","url":"","html_url":"","followers_url":"","following_url":"{/other_user}","gists_url":"{/gist_id}","starred_url":"{/owner}{/repo}","subscriptions_url":"","organizations_url":"","repos_url":"","events_url":"{/privacy}","received_events_url":"","type":"User","site_admin":false,"name":"roc","company":"Tencent","blog":"","location":"China","email":"[email protected]","hireable":true,"bio":"I'm roc","twitter_username":"imrocchan","public_repos":136,"public_gists":0,"followers":406,"following":155,"created_at":"2014-04-30T10:50:46Z","updated_at":"2022-05-03T12:12:52Z","private_gists":1,"total_private_repos":2,"owned_private_repos":2,"disk_usage":521309,"collaborators":0,"two_factor_authentication":true,"plan":{"name":"free","space":976562499,"collaborators":0,"private_repos":10000}}
roc's website: