dkapi

README

developerknowledge-go

Go helpers for the Google Developer Knowledge API.

This module is intentionally small. It provides shared primitives used by Developer Knowledge API clients:

• API key and ADC authentication helpers
• quota project handling for local ADC
• Google API error parsing
• rate limit error handling and Retry-After parsing
• context-aware HTTP request helpers
• documents:batchGet support
• shared Document and DocumentChunk response types
• conservative batch bisection error classification

Install

go get github.com/apstndb/developerknowledge-go@v0.1.0

Example

client, apiKey, err := dkapi.NewAuthenticatedHTTPClient(ctx, dkapi.AuthConfig{
    Mode:    dkapi.AuthPreferAPIKey,
    Timeout: dkapi.DefaultHTTPTimeout,
})
if err != nil {
    return err
}

dkClient := &dkapi.Client{
    BaseURL:    dkapi.DefaultV1BaseURL,
    APIKey:     apiKey,
    HTTPClient: client,
    Context:    ctx,
}

docs, err := dkClient.BatchGetDocuments([]string{
    "documents/developers.google.com/knowledge/api",
})

Documentation

Index

• Constants
• func APIKeyFromEnv() string
• func CheckResponse(resp *http.Response) ([]byte, error)
• func DefaultADCCredentialsPath(goos, homeDir, appData string) string
• func DefaultCredentialsPath() string
• func IsBisectableDocumentError(err error) bool
• func NewADCHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, error)
• func NewAuthenticatedHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, string, error)
• func NormalizeDocName(name string) string
• func ParseRetryAfter(resp *http.Response) time.Duration
• func SleepContext(ctx context.Context, wait time.Duration) error
• type ADCCredentialsMetadata
  • func LoadADCCredentialsMetadata(credentialsPath func() string) ADCCredentialsMetadata
  • func ResolveQuotaProjectID(credentialsPath func() string) (string, ADCCredentialsMetadata)
• type APIError
  • func (e *APIError) Error() string
• type AuthConfig
• type AuthMode
• type BatchGetResponse
• type Client
  • func (c *Client) BatchGetDocuments(names []string) ([]Document, error)
  • func (c *Client) DoAPIRequest(method, reqURL string, body []byte, contentType string) ([]byte, error)
  • func (c *Client) DoGet(reqURL string) ([]byte, error)
  • func (c *Client) DoJSONPost(reqURL string, body []byte) ([]byte, error)
• type Document
• type DocumentChunk
• type QuotaProjectTransport
  • func (t *QuotaProjectTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type RateLimitError
  • func (e *RateLimitError) Error() string
• type TokenSourceFunc
• type Waiter

Constants

const (
	CloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"
	DefaultV1BaseURL   = "https://developerknowledge.googleapis.com/v1"
	DefaultHTTPTimeout = time.Minute
)

Functions

func APIKeyFromEnv

func APIKeyFromEnv() string

func CheckResponse

func CheckResponse(resp *http.Response) ([]byte, error)

func DefaultADCCredentialsPath

func DefaultADCCredentialsPath(goos, homeDir, appData string) string

func DefaultCredentialsPath

func DefaultCredentialsPath() string

func IsBisectableDocumentError

func IsBisectableDocumentError(err error) bool

func NewADCHTTPClient

func NewADCHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, error)

func NewAuthenticatedHTTPClient

func NewAuthenticatedHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, string, error)

func NormalizeDocName

func NormalizeDocName(name string) string

func ParseRetryAfter

func ParseRetryAfter(resp *http.Response) time.Duration

func SleepContext

func SleepContext(ctx context.Context, wait time.Duration) error

Types

type ADCCredentialsMetadata

type ADCCredentialsMetadata struct {
	Type           string `json:"type"`
	QuotaProjectID string `json:"quota_project_id"`
}

func LoadADCCredentialsMetadata

func LoadADCCredentialsMetadata(credentialsPath func() string) ADCCredentialsMetadata

func ResolveQuotaProjectID

func ResolveQuotaProjectID(credentialsPath func() string) (string, ADCCredentialsMetadata)

type APIError

type APIError struct {
	Code    int
	Status  string
	Message string
}

func (*APIError) Error

func (e *APIError) Error() string

type AuthConfig

type AuthConfig struct {
	Mode            AuthMode
	Timeout         time.Duration
	TokenSource     TokenSourceFunc
	CredentialsPath func() string
}

type AuthMode

type AuthMode int

const (
	AuthPreferAPIKey AuthMode = iota
	AuthRequireADC
)

type BatchGetResponse

type BatchGetResponse struct {
	Documents []Document `json:"documents" yaml:"documents"`
}

type Client

type Client struct {
	BaseURL       string
	APIKey        string
	HTTPClient    *http.Client
	Context       context.Context
	Limiter       Waiter
	Verbose       bool
	VerboseWriter io.Writer
	// MaxRetries is the number of additional attempts after the first request.
	MaxRetries int
}

func (*Client) BatchGetDocuments

func (c *Client) BatchGetDocuments(names []string) ([]Document, error)

func (*Client) DoAPIRequest

func (c *Client) DoAPIRequest(method, reqURL string, body []byte, contentType string) ([]byte, error)

func (*Client) DoGet

func (c *Client) DoGet(reqURL string) ([]byte, error)

func (*Client) DoJSONPost

func (c *Client) DoJSONPost(reqURL string, body []byte) ([]byte, error)

type Document

type Document struct {
	Name        string `json:"name" yaml:"name"`
	URI         string `json:"uri" yaml:"uri"`
	Content     string `json:"content,omitempty" yaml:"content,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	DataSource  string `json:"dataSource,omitempty" yaml:"data_source,omitempty"`
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	UpdateTime  string `json:"updateTime,omitempty" yaml:"update_time,omitempty"`
	View        string `json:"view,omitempty" yaml:"view,omitempty"`
}

type DocumentChunk

type DocumentChunk struct {
	Parent   string    `json:"parent" yaml:"parent"`
	ID       string    `json:"id" yaml:"id"`
	Content  string    `json:"content" yaml:"content"`
	Document *Document `json:"document,omitempty" yaml:"document,omitempty"`
}

type QuotaProjectTransport

type QuotaProjectTransport struct {
	Base    http.RoundTripper
	Project string
}

func (*QuotaProjectTransport) RoundTrip

func (t *QuotaProjectTransport) RoundTrip(req *http.Request) (*http.Response, error)

type RateLimitError

type RateLimitError struct {
	RetryAfter time.Duration
}

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

type TokenSourceFunc

type TokenSourceFunc func(context.Context, ...string) (oauth2.TokenSource, error)

var DefaultTokenSource TokenSourceFunc = func(ctx context.Context, scopes ...string) (oauth2.TokenSource, error) {
	return google.DefaultTokenSource(ctx, scopes...)
}

type Waiter

type Waiter interface {
	Wait(context.Context) error
}