Documentation
¶
Overview ¶
Package apiclient provides small client-side helpers for api-toolkit APIs.
The package is stable core API for consumers that want composable helpers without generated service-specific SDKs. It decodes Problem Details responses, parses Retry-After, builds precondition headers, adds API key credentials, signs webhook requests, performs simple JSON requests, and iterates cursor-paginated resources.
Start with DoJSON for small JSON request/response flows, DecodeProblem when handling non-2xx responses, APIKeyTransport for service-to-service API key calls, WebhookSignerTransport for signed outbound webhook calls, and CursorIterator for cursor pages.
apiclient does not implement persistence, background retries, circuit breaking, generated resource clients, or provider-specific authentication. Keep those concerns in application clients or generated SDKs. For examples, see docs/cookbook.md.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/apiclient`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
- func DoJSON[T any](ctx context.Context, client *http.Client, method, url string, requestBody any) (T, *http.Response, error)
- func PreconditionHeaders(etag string, lastModified time.Time) http.Header
- func RetryAfter(header http.Header) (time.Duration, bool)
- type APIKeyTransport
- type CursorIterator
- type CursorPage
- type CursorPageFunc
- type ProblemError
- type WebhookSignerTransport
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DoJSON ¶
func DoJSON[T any](ctx context.Context, client *http.Client, method, url string, requestBody any) (T, *http.Response, error)
DoJSON sends a JSON request and decodes a JSON response.
func PreconditionHeaders ¶
PreconditionHeaders builds conditional request headers.
Example ¶
package main
import (
"fmt"
"time"
"github.com/aatuh/api-toolkit/v4/apiclient"
)
func main() {
lastModified := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)
headers := apiclient.PreconditionHeaders(`"widgets-v1"`, lastModified)
fmt.Println(headers.Get("If-Match"))
fmt.Println(headers.Get("If-Unmodified-Since"))
}
Output: "widgets-v1" Fri, 02 Jan 2026 03:04:05 GMT
Types ¶
type APIKeyTransport ¶
type APIKeyTransport struct {
Key string
HeaderName string
Scheme string
Base http.RoundTripper
}
APIKeyTransport adds API key credentials to outbound requests.
type CursorIterator ¶
type CursorIterator[T any] struct { Fetch CursorPageFunc[T] Cursor string // contains filtered or unexported fields }
CursorIterator iterates cursor-paginated resources.
func (*CursorIterator[T]) Err ¶
func (it *CursorIterator[T]) Err() error
Err returns the terminal iterator error.
func (*CursorIterator[T]) Items ¶
func (it *CursorIterator[T]) Items() []T
Items returns the current page items.
type CursorPage ¶
CursorPage is one cursor-paginated client page.
type CursorPageFunc ¶
CursorPageFunc fetches one cursor-paginated page.
type ProblemError ¶
ProblemError wraps a Problem Details response as an error.
func DecodeProblem ¶
func DecodeProblem(resp *http.Response) (*ProblemError, error)
DecodeProblem decodes a Problem Details response.
func (*ProblemError) Error ¶
func (err *ProblemError) Error() string
type WebhookSignerTransport ¶
type WebhookSignerTransport struct {
Signer webhooks.Signer
HeaderName string
Base http.RoundTripper
}
WebhookSignerTransport signs outbound request bodies.
Source Files