Documentation
¶
Overview ¶
Package api calls a JSON server — a Nimbus app — with typed endpoints. Declare each endpoint once, in a package both the server and the app import, and every call is checked by the compiler on both sides:
// shared/api.go
var ListOrders = api.GET[ListOrdersReq, []Order]("/api/orders")
var GetOrder = api.GET[OrderRef, Order]("/api/orders/{id}")
var CreateOrder = api.POST[NewOrder, Order]("/api/orders")
// in the app
client := api.New("https://example.com")
orders, err := api.Call(ctx, client, ListOrders, ListOrdersReq{Status: "paid"})
The package depends only on the standard library, so it is safe to import from shared code that also builds into the app.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Call ¶
func Call[Req, Resp any](ctx context.Context, c *Client, e Endpoint[Req, Resp], req Req) (Resp, error)
Call sends req to the endpoint and decodes the response. GET and DELETE send the request as query parameters (by json name, without the path parameters); the others as a JSON body — tag path fields json:"-" to keep them out of it.
Types ¶
type Client ¶
type Client struct {
BaseURL string
HTTP *http.Client
// Token, when set, is sent as "Authorization: Bearer <token>" (e.g. a
// Nimbus session or API token).
Token func() string
// Header adds headers to every request.
Header http.Header
}
Client sends requests to one server.
type Endpoint ¶
Endpoint is one route: its method and path, and the Go types of its request and response. Path parameters are written {name} and filled from the request field tagged `path:"name"`.
Source Files