prest

README

integration/prest

The prest package provides a generic HTTP client for pREST APIs. It is intended for services that consume a pREST backend and need automatic OAuth2 client credentials authentication, transparent token refresh, and typed JSON response unmarshalling without writing that plumbing in every call site.

Import

import "github.com/raykavin/gobox/integration/prest"

What it provides

• Client[T] for sending authenticated GET requests to a pREST API
• automatic OAuth2 client credentials token acquisition and caching
• transparent token refresh when the cached token is about to expire
• GetPaginated() for adding limit and offset query parameters
• Reset() for forcing re-authentication on the next request

Main types

• Client[T]: generic client that returns T from JSON responses

Example

package main

import (
    "context"
    "log"

    "github.com/raykavin/gobox/integration/prest"
)

type Order struct {
    ID     int     `json:"id"`
    Total  float64 `json:"total"`
    Status string  `json:"status"`
}

func main() {
    client, err := prest.NewClient[[]Order](
        "my-client-id",
        "my-client-secret",
        "client_credentials",
        "orders:read",
        "https://auth.example.com/oauth/token",
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // first page
    orders, err := client.GetPaginated(ctx, "https://api.example.com/public.orders", 50, 0)
    if err != nil {
        log.Fatal(err)
    }

    for _, o := range orders {
        log.Printf("order %d: %s (%.2f)", o.ID, o.Status, o.Total)
    }
}

Notes

• NewClient validates that clientID, clientSecret, grantType, scope, and authEndpoint are all non-empty; it does not make any network calls at construction time
• the token is cached in memory and reused across requests; it is considered expired 10s before the expires_in value from the token response
• pass a custom *http.Client as the last argument to NewClient to control timeouts and transport; the default is http.DefaultClient
• Reset() clears the cached token without making a network call; the next request will re-authenticate
• Get and GetPaginated return an error for any non-200 HTTP status code

Documentation

Overview

Package prest provides a generic HTTP client for pREST APIs that authenticates automatically via OAuth2 client credentials.

Client[T] fetches and caches an access token, refreshing it before expiry, and unmarshals JSON responses directly into T.

Basic usage

type Product struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
}

client, err := prest.NewClient[[]Product](
    "client-id",
    "client-secret",
    "client_credentials",
    "api:read",
    "https://auth.example.com/oauth/token",
)
if err != nil {
    log.Fatal(err)
}

products, err := client.Get(ctx, "https://api.example.com/products", nil)

Pagination

page, err := client.GetPaginated(ctx, "https://api.example.com/products", 50, 0)

Index

• Variables
• type Client
  • func NewClient[T any](clientID string, clientSecret string, grantType string, scope string, ...) (*Client[T], error)
  • func (c *Client[T]) Get(ctx context.Context, endpoint string, params map[string]string) (T, error)
  • func (c *Client[T]) GetPaginated(ctx context.Context, endpoint string, limit, offset int) (T, error)
  • func (c *Client[T]) Reset()

Variables

var (
	ErrInvalidCredentials = errors.New("invalid credentials")
	ErrInvalidEndpoints   = errors.New("invalid endpoints")
)

Types

type Client

type Client[T any] struct {
	// contains filtered or unexported fields
}

Client is a generic pREST API client that authenticates via OAuth2 client credentials and unmarshals responses into T.

func NewClient

func NewClient[T any](
	clientID string,
	clientSecret string,
	grantType string,
	scope string,
	authEndpoint string,
	client ...*stdhttp.Client,
) (*Client[T], error)

NewClient creates a new pREST Client.

func (*Client[T]) Get

func (c *Client[T]) Get(ctx context.Context, endpoint string, params map[string]string) (T, error)

Get sends a GET request to endpoint, appending the given query params, and unmarshals the JSON response body into T.

func (*Client[T]) GetPaginated

func (c *Client[T]) GetPaginated(ctx context.Context, endpoint string, limit, offset int) (T, error)

GetPaginated sends a GET request with limit/offset pagination query params.

func (*Client[T]) Reset

func (c *Client[T]) Reset()

Reset clears the cached authentication token, forcing re-authentication on the next request.