Documentation
¶
Overview ¶
Package api holds REST helpers on top of web and orm: resource transformers, pagination envelopes, allowlisted query conventions (filter, sort, fields, include, pagination) and deprecation headers. See docs/api.md.
Index ¶
- func Collection[T, R any](c *web.Ctx, items []T, fn func(T) R) error
- func Cursor[T, R any](c *web.Ctx, p orm.CursorPage[T], fn func(T) R) error
- func Deprecate(since, sunset time.Time, link string) func(http.Handler) http.Handler
- func Map[T, R any](items []T, fn func(T) R) []R
- func Page[T, R any](c *web.Ctx, p orm.Page[T], fn func(T) R) error
- type Envelope
- type Links
- type Meta
- type Option
- type Request
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Collection ¶
Collection answers 200 with {"data": [...]}.
func Cursor ¶
Cursor answers 200 with a keyset page: meta.next_cursor and links.next (null on the last page).
func Deprecate ¶
Deprecate marks routes as deprecated (RFC 9745 Deprecation and RFC 8594 Sunset headers) and links to the replacement or migration guide. Apply it to a version group: g.Use(api.Deprecate(since, sunset, "/docs/v2")).
Types ¶
type Envelope ¶
type Envelope[R any] struct { Data []R `json:"data"` Meta *Meta `json:"meta,omitempty"` Links *Links `json:"links,omitempty"` }
Envelope is the JSON body of collections and pages.
type Links ¶
type Links struct {
Self string `json:"self"`
Next *string `json:"next"`
Prev *string `json:"prev"`
}
Links point to neighbour pages; nil encodes as null.
type Meta ¶
type Meta struct {
Page int `json:"page,omitempty"`
PerPage int `json:"per_page"`
Total *int64 `json:"total,omitempty"`
LastPage int `json:"last_page,omitempty"`
NextCursor string `json:"next_cursor,omitempty"`
}
Meta describes a page.
type Option ¶
type Option func(*spec)
Option allowlists one query convention for an endpoint.
type Request ¶
type Request[T any] struct { Query orm.Query[T] Page int PerPage int Cursor string Includes []string }
Request is a query refined by the allowlisted conventions.
Source Files