endpoint

Documentation

Index

• func ApplyQueryParamsFn(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, qp map[string]string) error
• func BuildRequest(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) (*client.Request, error)
• func ExtractItems(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, raw any) []any
• func FetchAll(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) ([]any, *cmdctx.PageMeta, error)
• func FetchCount(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) (int64, error)
• func FetchItems(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, pf cmdctx.PagingFlags) ([]any, *cmdctx.PageMeta, error)
• func FetchRange(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, wantStart, wantCount int) ([]any, *cmdctx.PageMeta, error)
• func HTTPFetchFn(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, wantStart, wantCount int, cursor any) (*cmdctx.PageResult, error)
• func ResolveFetchFn(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) (cmdctx.FetchFn, error)
• type PagingStrategy
  • func MakePagingStrategy(strategyName string) (PagingStrategy, error)

Functions

func ApplyQueryParamsFn

func ApplyQueryParamsFn(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, qp map[string]string) error

ApplyQueryParamsFn calls ep.QueryParamsFn (if set) and merges the returned params into qp, overwriting any existing keys with non-empty values.

func BuildRequest

func BuildRequest(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) (*client.Request, error)

BuildRequest resolves path and base query params from ctx and ep into a client.Request.

func ExtractItems

func ExtractItems(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, raw any) []any

ExtractItems applies ep.ItemsExpr to raw and returns the resulting slice. Returns nil when the expression doesn't resolve.

func FetchAll

func FetchAll(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) ([]any, *cmdctx.PageMeta, error)

FetchAll fetches every available item from offset 0.

func FetchCount

func FetchCount(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) (int64, error)

FetchCount returns the total number of items available without fetching them all. For strategies that return a total in the first response (page_index, page_header) this is a single API call. For flat_list it fetches everything and counts. Returns an error if the endpoint does not support counting.

func FetchItems

func FetchItems(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, pf cmdctx.PagingFlags) ([]any, *cmdctx.PageMeta, error)

FetchItems normalizes PagingFlags into the appropriate FetchRange/FetchAll call. --all maps to FetchAll; otherwise FetchRange is called with the offset/limit from flags.

func FetchRange

func FetchRange(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, wantStart, wantCount int) ([]any, *cmdctx.PageMeta, error)

FetchRange fetches items [wantStart, wantStart+wantCount) using the FetchFn resolved from ep. It is strategy-blind: all paging knowledge lives in the FetchFn. If wantCount is 0 it defaults to defaultPageSize.

func HTTPFetchFn

func HTTPFetchFn(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, wantStart, wantCount int, cursor any) (*cmdctx.PageResult, error)

HTTPFetchFn is the default FetchFn for spec-declared endpoints. It composes BuildRequest → InjectPaging → DoRequest → ExtractItems → ExtractPaging.

func ResolveFetchFn

func ResolveFetchFn(ctx *cmdctx.Ctx, ep *spec.EndpointSpec) (cmdctx.FetchFn, error)

ResolveFetchFn returns the FetchFn to use for ep. If ep.FetchFn is set it is looked up through ctx.Resolver; otherwise HTTPFetchFn is returned.

Types

type PagingStrategy

type PagingStrategy interface {
	InjectPaging(req *client.Request, pg *spec.PagingSpec, wantStart, wantCount int) any
	ExtractPaging(ctx *cmdctx.Ctx, ep *spec.EndpointSpec, raw any, items []any, headers http.Header, pagingData any) (*cmdctx.PageResult, error)
}

PagingStrategy encapsulates the inject/extract logic for one paging style. InjectPaging mutates req with the appropriate query params and returns opaque state that ExtractPaging will need to interpret the response. ExtractPaging builds a PageResult from the raw response, response headers, and the opaque state produced by InjectPaging.

func MakePagingStrategy

func MakePagingStrategy(strategyName string) (PagingStrategy, error)

MakePagingStrategy returns the PagingStrategy implementation for strategyName.