Links and versions
ApiLink
Tomaj\NetteApi\Link\ApiLink builds URLs through the Nette router, so links follow your route:
$url = $apiLink->link(new EndpointIdentifier('GET', 1, 'users', 'detail'), ['id' => 5]);It needs a route to Api:Api:default with version, package and apiAction parameters, as in Getting started.
For an endpoint whose URL has {name} segments, such as {id}/detail, link() fills each segment from the parameter of the same name (URL-encoded); the other parameters go to the query string. A segment without a value stays literal, which is the OpenAPI path template. A path value '', '.', '..' or one with a slash throws Nette\Application\UI\InvalidLinkException, because such a segment would never match or would lead to another URL. BaseHandler::createLink() fills the segments the same way. The route mask must have <package> and <apiAction> as path segments:
$url = $apiLink->link(new EndpointIdentifier('GET', 1, 'users', '{id}/detail'), ['id' => 42, 'limit' => 5]);
// https://example.com/api/v1/users/42/detail?limit=5
$url = $apiLink->link(new EndpointIdentifier('GET', 1, 'users', '{id}/detail'));
// https://example.com/api/v1/users/{id}/detailInside a handler extending BaseHandler or TypedHandler, call $this->createLink($params) for a link to the handler's own endpoint. It needs Nette's LinkGenerator first, otherwise it throws Nette\InvalidStateException. Add a setup line to the handler service:
services:
-
factory: App\Api\UserDetailHandler
setup:
- setupLinkGenerator(@Nette\Application\LinkGenerator)See also Handlers.
The {apiLink} tag
<a href="{apiLink 'GET', '1', 'openapi', null, ['format' => 'yaml']}">YAML</a>Arguments are method, version, package, action and params. Register the extension and the apiLink filter that the tag calls:
latte:
extensions:
- Tomaj\NetteApi\Link\ApiLinkExtension
services:
apiLink: Tomaj\NetteApi\Link\ApiLink
latte.latteFactory:
setup:
- addFilter(apiLink, [@apiLink, link])The older ApiLinkMacro from 2.x does not exist in 3.x.
Versions
The version is part of every EndpointIdentifier and of the URL, /api/v1/users, /api/v2/users. Register both and keep the old handler until clients move:
- addApi(Tomaj\NetteApi\EndpointIdentifier('GET', 1, 'users'), App\Api\V1\UserListHandler, ...)
- addApi(Tomaj\NetteApi\EndpointIdentifier('GET', 2, 'users'), App\Api\V2\UserListHandler, ...)A version can be a number or a string like '1.1', without /. Mark the old handler with deprecated() so OpenAPI shows it.
FAQ
Why does ApiLink return an empty string?
No route matched Api:Api:default with those parameters. Check the route mask and the Api mapping.
Can one handler serve several versions?
Yes, register the same class twice and read $this->getEndpoint()->getVersion().
Does each version need its own OpenAPI endpoint?
Yes, OpenAPI lists only its own version.
Is this page about the version of the library?
No, this is your API's version. For the library see Versions of this documentation.
Where is a working {apiLink} template?
In the OpenAPI and console example.