Provider¶

An API family: base URL, auth, pagination, error semantics and rate limits.

Schema: provider.json. Explanations and examples: configuration model.

Field	Type	Required	Description
`apiVersion`	`tapyr/v1alpha1`	yes	Version of the configuration format.
`kind`	`Provider`	yes	Kind of the document.
`metadata`	ProviderMeta	yes	Name and description of the document.
`spec`	ProviderSpec	yes	Specification of the document.

ProviderMeta¶

ProviderMeta identifies a provider package.

Field	Type	Required	Description
`description`	string		Description is free text for humans.
`docs`	string		Docs links to the vendor API documentation. Format uri.
`name`	Name	yes	Name of the provider, unique across built-in and user packages.
`version`	string	yes	Version of the provider package (semver). Breaking changes to metric names or labels bump the major version. Pattern `^(0\|[1-9][0-9])\.(0\|[1-9][0-9])\.(0\|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$`.

ProviderSpec¶

ProviderSpec is the specification of a Provider.

Field	Type	Required	Description
`auth`	Auth		Auth applied to every request. Defaults to type none.
`baseURL`	Template	yes	`baseURL` of the API. Template evaluated per account and target, for example {{ .params.baseURL \| default "https://api.example.com/v1" }}.
`defaults`	RequestDefaults		Defaults applied to every request.
`errors`	ErrorSemantics		Errors declares how the API signals rate limiting, authentication failures and retryable errors.
`limits`	list of Limit		Limits declares every rate limit, concurrency limit and quota of the API.
`pagination`	Pagination		Pagination used by job templates that do not override it.
`params`	list of ParamSpec		Params an Account may or must provide.
`redirects`	Redirects		Redirects lists the other hosts a response may redirect requests to. Redirects to another host are not followed otherwise: credentials only go to the base URL and to these hosts.
`secrets`	list of ParamSpec		Secrets an Account may or must provide.

Name¶

Type: string. Pattern ^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$.

Auth¶

Auth configures authentication.

Field	Type	Required	Description
`basic`	BasicAuth		Basic sends HTTP basic credentials (type basic).
`bearer`	BearerAuth		Bearer sends Authorization: Bearer <token> (type bearer).
`header`	HeaderAuth		Header sends a static value in a header (type header).
`oauth2ClientCredentials`	OAuth2ClientCredentials		`oauth2ClientCredentials` obtains tokens with the OAuth 2.0 client credentials grant (type oauth2_client_credentials).
`plugin`	PluginAuth		Plugin delegates to a Go auth plugin (type plugin).
`sessionLogin`	SessionLogin		`sessionLogin` posts credentials to obtain a session token (type session_login).
`type`	string	yes	Type of authentication. One of `none`, `header`, `bearer`, `basic`, `oauth2_client_credentials`, `session_login`, `plugin`.

When type is basic: basic is required.
When type is bearer: bearer is required.
When type is header: header is required.
When type is oauth2_client_credentials: oauth2ClientCredentials is required.
When type is plugin: plugin is required.
When type is session_login: sessionLogin is required.

Template¶

Go text/template evaluated per account and target.

Type: string.

RequestDefaults¶

RequestDefaults are applied to every request of the provider.

Field	Type	Required	Description
`headers`	map of string to Template		Headers added to every request. Values are templates.
`timeout`	Duration		Timeout of a single request. Defaults to settings.collection.defaultTimeout.

ErrorSemantics¶

ErrorSemantics declares how the provider signals errors.

Field	Type	Description
`authFailed`	StatusMatcher	`authFailed` matches authentication failures (default 401).
`rateLimited`	RateLimitedErrors	`rateLimited` matches rate-limited responses.
`retryable`	StatusMatcher	Retryable matches transient errors (default 500, 502, 503, 504).

Limit¶

Limit is a constraint of the provider API, enforced by the budget engine for every request (see docs/spec/04-budget-engine.md).

Field	Type	Required	Description
`appliesTo`	AppliesTo		`appliesTo` restricts the requests the limit counts.
`burst`	integer		Burst is the bucket capacity of a rate limit. Defaults to the rate per second, minimum 1. Minimum 1.
`description`	string		Description is free text for humans, ideally with the source of the limit.
`initialMax`	integer		`initialMax` is the conservative quota maximum used with max: auto until the first limit header is observed. Minimum 1.
`kind`	string	yes	Kind of limit: rate (token bucket), concurrency or quota (window). One of `rate`, `concurrency`, `quota`.
`max`	IntOrAuto		Max is the maximum of a concurrency limit, or of a quota per window. A quota may use "auto" to learn it from response headers.
`name`	Name	yes	Name of the limit, unique within the provider.
`rate`	Rate		Rate is the refill rate of a rate limit, for example 10/s.
`scope`	Scope		Scope partitions the limit (one counter per scope key).
`sync`	QuotaSync		Sync reads quota state from response headers.
`window`	Window		Window of a quota: a calendar period or a rolling duration.

When kind is rate: rate is required.
When kind is concurrency: max is required.
When kind is quota: max and window are required.

Pagination¶

Pagination configures how successive pages are requested.

Field	Type	Required	Description
`cursor`	CursorPagination		Cursor pagination (type cursor).
`expression`	ExpressionPagination		Expression pagination computed by CEL (type expression).
`linkHeader`	LinkHeaderPagination		`linkHeader` pagination following RFC 8288 Link headers (type link_header).
`maxPages`	integer		`maxPages` is a hard safety cap on pages per run. Default `100`. Minimum 1.
`offset`	OffsetPagination		Offset pagination (type offset).
`page`	PagePagination		Page pagination (type page).
`type`	string	yes	Type of pagination. One of `none`, `offset`, `page`, `link_header`, `cursor`, `expression`.

When type is offset: offset is required.
When type is page: page is required.
When type is cursor: cursor is required.
When type is expression: expression is required.

ParamSpec¶

ParamSpec declares a param or a secret that accounts provide.

Field	Type	Required	Description
`description`	string		Description is free text for humans.
`name`	Identifier	yes	Name of the param or secret.
`required`	boolean		Required makes the param or secret mandatory for every account (or every target of a multi-target account).

Redirects¶

Redirects allows HTTP redirects to other hosts.

Field	Type	Required	Description
`hosts`	list of string	yes	Hosts the requests may be redirected to: a host name, or "." and a domain for every host under it (for example ".meraki.com"). Minimum items 1.

BasicAuth¶

BasicAuth sends HTTP basic credentials.

Field	Type	Required	Description
`password`	Value	yes	Password, usually {secret: name}.
`username`	Value	yes	Username, a literal or {secret: name}.

BearerAuth¶

BearerAuth sends Authorization: Bearer <token>.

Field	Type	Required	Description
`token`	Value	yes	Token, usually {secret: name}.

HeaderAuth¶

HeaderAuth sends a static credential in a request header.

Field	Type	Required	Description
`name`	string	yes	Name of the header, for example X-API-Key. Minimum length 1.
`value`	Value	yes	Value of the header, usually {secret: name}.

OAuth2ClientCredentials¶

OAuth2ClientCredentials configures the OAuth 2.0 client credentials grant.

Field	Type	Required	Description
`audience`	string		Audience requested, when the server requires one.
`authStyle`	string		`authStyle` sends the client credentials in the Authorization header or in the request body. Default `header`. One of `header`, `body`.
`clientId`	Value	yes	ClientID, a literal or {secret: name}.
`clientSecret`	Value	yes	ClientSecret, usually {secret: name}.
`extraParams`	map of string to string		`extraParams` added to the token request.
`scopes`	list of string		Scopes requested.
`tokenURL`	Template	yes	`tokenURL` of the authorization server. Template.

PluginAuth¶

PluginAuth selects a Go auth plugin, for flows that cannot be expressed declaratively.

Field	Type	Required	Description
`config`	object		Config is passed to the plugin, which validates it.
`name`	string	yes	Name of the plugin, as registered in internal/auth/plugins. Pattern `^[a-z][a-z0-9_]*$`.

SessionLogin¶

SessionLogin posts credentials to a login endpoint and applies the returned token to subsequent requests.

Field	Type	Required	Description
`apply`	TokenApply	yes	Apply describes how the token is attached to requests.
`expiresIn`	Expr		`expiresIn` is a CEL expression returning the token lifetime as a duration.
`logout`	LogoutRequest		Logout closes a session when its token is replaced and when Tapyr stops, for APIs that keep sessions open until they are closed.
`perTarget`	boolean		`perTarget` keeps one session per target of a multi-target account.
`refreshBefore`	Duration		`refreshBefore` renews the session this long before it expires. Default `30s`.
`request`	LoginRequest	yes	Request is the login request.
`token`	Expr	yes	Token is a CEL expression extracting the token from the login response.

Duration¶

Type: string. Pattern ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$. Examples 30s, 5m, 1h30m.

StatusMatcher¶

StatusMatcher matches responses by HTTP status code.

Field	Type	Required	Description
`statuses`	list of integer		Statuses that match. Minimum items 1. Each item: minimum 100, maximum 599.

RateLimitedErrors¶

RateLimitedErrors matches rate-limited responses and configures penalties.

Field	Type	Description
`defaultPenalty`	Duration	`defaultPenalty` applies when no Retry-After header is present. It grows exponentially on consecutive rate-limited responses, up to 10 minutes. Default `2s`.
`penalize`	string	Penalize the narrowest applicable scope, or all applicable scopes. Default `narrowest`. One of `narrowest`, `all`.
`retryAfterHeader`	string	`retryAfterHeader` carries the penalty in seconds or as an HTTP date. Default `Retry-After`.
`statuses`	list of integer	Statuses that signal rate limiting (default 429). Minimum items 1. Each item: minimum 100, maximum 599.

AppliesTo¶

AppliesTo restricts the requests a limit counts.

Field	Type	Description
`authRequests`	string	`authRequests` selects regular requests and token requests: include (both), only (token requests only) or exclude (regular requests only). Default `include`. One of `include`, `only`, `exclude`.
`endpoints`	list of string	Endpoints are globs on the templated path: * matches within one segment, ** matches any number of segments. Each item: pattern `^/`.
`methods`	list of string	Methods the limit counts. Each item: one of `GET`, `HEAD`, `POST`.
`requestsWithVar`	Identifier	`requestsWithVar` counts only requests where this variable is set.

IntOrAuto¶

Type: integer or string. Pattern ^auto$. Minimum 1.

Rate¶

Type: string. Pattern ^[0-9]+(\.[0-9]+)?/(s|m|h)$. Examples 10/s, 600/m.

Scope¶

Scope partitions a limit.

Field	Type	Required	Description
`by`	list of string		By lists the scope dimensions: instance, provider, account, target, credential, endpoint or var:<name>. Empty means instance. Unique items. Each item: pattern `^(instance\|provider\|account\|target\|credential\|endpoint\|var:[A-Za-z_][A-Za-z0-9_]*)$`.

QuotaSync¶

QuotaSync names the response headers carrying quota state.

Field	Type	Description
`limitHeader`	string	`limitHeader` carries the quota maximum.
`remainingHeader`	string	`remainingHeader` carries the remaining quota.
`resetHeader`	string	`resetHeader` carries the reset time (epoch seconds or delta seconds).

Window¶

Window is the window of a quota: exactly one of period or rolling.

Field	Type	Description
`monthDay`	integer	`monthDay` is the day of month windows reset (1 to 31; the last day of shorter months). Default `1`. Minimum 1. Maximum 31.
`period`	string	Period of a fixed calendar window. One of `minute`, `hour`, `day`, `week`, `month`.
`resetAt`	string	`resetAt` is the time of day (HH:MM, 24h) at which day, week and month windows reset. Default `00:00`. Pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$`.
`rolling`	Duration	Rolling is the duration of a rolling window (1-minute precision).
`timezone`	string	Timezone of the calendar (IANA name). Default `UTC`.
`weekStart`	string	`weekStart` is the first day of week windows. Default `monday`. One of `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.

CursorPagination¶

CursorPagination passes a cursor extracted from each response.

Field	Type	Required	Description
`cursor`	Expr	yes	Cursor is a CEL expression extracting the next cursor; empty or null stops.
`header`	string		Header carrying the cursor, instead of a query parameter.
`pageSize`	integer		`pageSize` is the number of items per page. Minimum 1.
`pageSizeParam`	string		`pageSizeParam` is the query parameter carrying the page size.
`param`	string		Param is the query parameter carrying the cursor.

ExpressionPagination¶

ExpressionPagination computes the next request with CEL.

Field	Type	Required	Description
`next`	Expr	yes	Next is a CEL expression returning {query: {...}} for the next page, or null.

LinkHeaderPagination¶

LinkHeaderPagination follows RFC 8288 Link headers.

Field	Type	Description
`pageSize`	integer	`pageSize` is the number of items per page. Minimum 1.
`pageSizeParam`	string	`pageSizeParam` is the query parameter carrying the page size.
`rel`	string	Rel is the link relation of the next page. Default `next`.

OffsetPagination¶

OffsetPagination requests pages by item offset.

Field	Type	Required	Description
`limitParam`	string	yes	`limitParam` is the query parameter carrying the page size. Minimum length 1.
`offsetParam`	string	yes	`offsetParam` is the query parameter carrying the offset. Minimum length 1.
`pageSize`	integer	yes	`pageSize` is the number of items per page. Minimum 1.
`start`	integer		Start is the first offset. Default `0`. Minimum 0.
`stop`	Expr		Stop is a CEL expression; pagination stops when it returns true.
`total`	Expr		Total is a CEL expression returning the total number of items.

PagePagination¶

PagePagination requests pages by page number.

Field	Type	Required	Description
`pageParam`	string	yes	`pageParam` is the query parameter carrying the page number. Minimum length 1.
`pageSize`	integer		`pageSize` is the number of items per page. Minimum 1.
`sizeParam`	string		`sizeParam` is the query parameter carrying the page size.
`start`	integer		Start is the first page number. Default `1`. Minimum 0.
`stop`	Expr		Stop is a CEL expression; pagination stops when it returns true.
`total`	Expr		Total is a CEL expression returning the total number of items.

Identifier¶

Type: string. Pattern ^[A-Za-z_][A-Za-z0-9_]*$.

Value¶

A literal string, {secret: name} or {expr: cel}.

Either a string, or an object:

Field	Type	Required	Description
`expr`	string		CEL expression evaluated at runtime. Minimum length 1.
`secret`	string		Name of a secret declared by the provider and supplied by the account. Pattern `^[A-Za-z_][A-Za-z0-9_]*$`.

Exactly one field is set.

TokenApply¶

TokenApply attaches a session token to requests, as a header or a cookie.

Field	Type	Description
`cookie`	string	Cookie that carries the token.
`format`	string	Format of the header value; {token} is replaced by the token. Default `{token}`.
`header`	string	Header that carries the token.

Expr¶

CEL expression.

Type: string. Minimum length 1.

LogoutRequest¶

LogoutRequest is the request that closes a session, sent with the token applied.

Field	Type	Required	Description
`method`	string		Method of the logout request. Default `POST`. One of `POST`, `GET`, `DELETE`.
`path`	string	yes	Path of the logout endpoint, relative to the base URL. Pattern `^/`.

LoginRequest¶

LoginRequest is the request that opens a session.

Field	Type	Required	Description
`body`	map of string to Value		Body is a JSON object; values are literals, secrets or CEL expressions.
`headers`	map of string to string		Headers added to the login request.
`method`	string		Method of the login request. Default `POST`. One of `POST`, `GET`.
`path`	string	yes	Path of the login endpoint, relative to the base URL. Pattern `^/`.