Documentation
¶
Overview ¶
Package binding decodes HTTP request body, query, and path values into typed structs and returns api-toolkit field errors.
Use this package at transport boundaries when a handler needs a small, dependency-neutral decoder that produces the same validation Problem Details shape as the rest of the toolkit. Business validation and persistence rules should still live outside handlers.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/binding`. 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 DecodeJSON[T any](r *http.Request, cfg JSONConfig) (T, error)
- func DecodePath[T any](r *http.Request, cfg PathConfig) (T, error)
- func DecodeQuery[T any](r *http.Request, cfg QueryConfig) (T, error)
- func ValidationProblem(err error) httpx.Problem
- func WriteValidationProblem(w http.ResponseWriter, err error)
- type JSONConfig
- type PathConfig
- type QueryConfig
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeJSON ¶
func DecodeJSON[T any](r *http.Request, cfg JSONConfig) (T, error)
DecodeJSON decodes a JSON body into T.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"github.com/aatuh/api-toolkit/v4/binding"
)
type exampleCreateWidget struct {
Name string `json:"name" required:"true"`
Quantity int `json:"quantity" required:"true"`
}
func main() {
req := httptest.NewRequestWithContext(
context.Background(),
http.MethodPost,
"/widgets",
strings.NewReader(`{"name":"starter","quantity":2}`),
)
widget, err := binding.DecodeJSON[exampleCreateWidget](req, binding.JSONConfig{MaxBytes: 1 << 20})
if err != nil {
panic(err)
}
fmt.Println(widget.Name, widget.Quantity)
}
Output: starter 2
func DecodePath ¶
func DecodePath[T any](r *http.Request, cfg PathConfig) (T, error)
DecodePath decodes route path parameters into T.
func DecodeQuery ¶
func DecodeQuery[T any](r *http.Request, cfg QueryConfig) (T, error)
DecodeQuery decodes query parameters into T.
func ValidationProblem ¶
ValidationProblem maps validation errors to a Problem Details payload.
func WriteValidationProblem ¶
func WriteValidationProblem(w http.ResponseWriter, err error)
WriteValidationProblem writes validation errors as RFC 9457 Problem Details.
Types ¶
type JSONConfig ¶
JSONConfig configures JSON request body decoding.
type PathConfig ¶
PathConfig configures path decoding.
Source Files