UPGRADE

Upgrade from 1.x to 2.0.0

Splitted InputParam to multiple subclasses

InputParam is now abstract class and all types have their own classes. Also InputParam is more like Nette Form inputs with fluent API.

Examples of replacements:

Required GET input with available values:

Old:

new InputParam(InputParam::TYPE_GET, 'status', InputParam::REQUIRED, ['ok', 'error'])

New:

(new GetInputParam('status'))->setRequired()->setAvailableValues(['ok', 'error'])

Multiple optional FILE input:

Old:

new InputParam(InputParam::TYPE_FILE, 'myfile', InputParam::OPTIONAL, null, true)

New:

(new FileInputParam('myfile'))->setMulti()

For more info about types, see readme section Input Types.

Removed support for old PHP versions

New version does not support PHP versions 5.6 and 7.0 and also hhvm. Please use it with newer versions of PHP (>7.1)

Updated dependencies

Version 2.0.0 requires nette packages in version 3.0, so probably you will have to upgrade whole nette application.

Typehints

There are some breaking changes because of added typehints:

ApiAuthorizationInterface

Add typehints to methods:

• authorized(): bool
• getErrorMessage(): ?string

ApiHandlerInterface

Add typehints to methods:

• params(): array
• handle(array $params): Tomaj\NetteApi\Response\ResponseInterface

ApiLoggerInterface

Add typehints to method:

• log(int $responseCode, string $requestMethod, string $requestHeader, string $requestUri, string $requestIp, string $requestAgent, int $responseTime): bool

BearerTokenRepositoryInterface

Add typehints to methods:

• validToken(string $token): bool
• ipRestrictions(string $token): ?string

IpDetectorInterface

Add typehints to method:

• getRequestIp(): string

ParamInterface

Add typehints to methods:

• isValid(): bool
• getKey(): string

EndpointInterface

Add typehints to methods:

• getMethod(): string
• getVersion(): int
• getPackage(): string
• getApiAction(): ?string
• getUrl(): string

Changed behavior

API handler tripplet (array of endpoint, handler, authorization) has been changed to class Api which has methods getEndpoint(), getHandler() and getAuthorization().

Renamed methods

Few methods have been renamed, please use their new versions:

• ApiDecider::addApiHandler() -> ApiDecider::addApi()
• ApiDecider::getApiHandler() -> ApiDecider::getApi()
• ApiDecider::getHandlers() -> ApiDecider::getApis()

Final methods

BaseHandler now have few final methods:

• setEndpointIdentifier
• getEndpoint
• setupLinkGenerator
• createLink

Removed class

Class ApiResponse has been removed. Use JsonApiResponse instead.

Removed params

Parameters $parent and $name have been removed from ApiListingControl. New usage is:

new ApiListingControl($apiDecider)

Changed params

Some parameters were strictly typed:

• second parameter in JsonApiResponse::__construct ($payload formerly known as $data) is now array
• fifth parameter in JsonApiResponse::__construct ($expiration) is now DateTimeInteface or null
• fourth parameter in InputParam::__construct ($availableValues, now parameter of method setAvailableValues()) is now array

Changed events

Registration of event onClick in ApiListingControl has been changed. Use:

$apiListing->onClick[] = function ($method, $version, $package, $apiAction) {
    ...
};

Features

With new version of Nette API you can:

• add description to your API handlers, also you can mark some handlers as deprecated and add tags for them.
• add description, default value and example for all your input params.
• add list of possible outputs which are validate before response is sent to user. If output is not valid, error is sent.

FAQ

Is there a guide for 2.x to 3.0?

Not a separate one. The breaking changes of 3.0.0 are the [BC] items in the changelog: DefaultHandler answers 404 instead of 400, ApiDecider gets the DI container, and the output configurator and error handler must be registered as services.

Is there a 4.0 to upgrade to?

Not yet. 3.x is the current line. 4.0 is in development on master: it needs PHP 8.4 or newer and its breaking changes so far are in UPGRADE-4.0.md. A 4.0.0 milestone is open with planned breaking changes, such as removing the unsafe 'auto' CORS mode and raising the minimum PHP version. It has no release date yet; see Versions of this documentation.

Which PHP version does 3.x need?

PHP 8.3 or newer, see Getting started.