Download the PHP package tomaj/nette-api without Composer

This simple handler is using UsersRepository that was created by Nette Container (so you have to register your App\MyApi\v1\Handlers\UsersListingHandler in config.neon).

Advanced use (with Fractal)

Nette-Api provides integration with Fractal library for formatting API responses. If you want to use it, you have to extend your handler from BaseHandler and your Fractal instance will be accessible by $this->getFractal().

Main advantage of Fractal is separation of your API "view" (like transformation data to json object or xml or anything...). Also you can include transformations in other transformations to include other objects to others.

Example with fractal:

1. You will need Transformer

2. And this will be your handler:

We recommend to take a look at Fractal library. There are much more information about transformers, serializers, paginations etc. It is really nice library.

ApiLink in latte

First, you have to register filter in config.neon:

Note: Name of filter has to be apiLink, because it is used in macro / extension.

For latte < 3.0 register latte macro:

For latte >= 3.0 register latte extension:

Usage in latte files:

Endpoint inputs

Each handler can describe which input is required. It could be GET or POST parameters, also COOKIES, raw post, JSON or file uploads. You have to implement method params() where you have to return array with params. These params are used in API console to generate form.

Example with user detail:

Input Types

Nette-Api provides various InputParam types. You can send params with GET, POST, COOKIES, FILES, RAW POST data or JSON. All input types are available via test console.

This is table with supported input types:

Outputs

By implementing method outputs for your handlers you can specify list of possible outputs (e.g. output schemas) and those will be validated before response is sent to user. If no outputs are set, response is sent to user without validating.

Usage example:

For more examples see JSON schema web page. Keep in mind that nette api uses justinrainbow/json-schema for validating schemas and this package supports only json schema draft 03 and 04.

Security

Protecting your API is easy with Nette-Api. You have to implement your Authorization (Tomaj\NetteApi\Authorization\ApiAuthorizationInterface) or use prepared implementations and add it as third argument to addApi() method in config.neon.

Basic authentication

Basic authentication is a simple authentication scheme built into the HTTP protocol. It contains username and password. You can define as many pairs of usernames and passwords as you want. But just one password for each username.

Bearer token authentication

For simple use of Bearer token authorization with few tokens, you can use StaticTokenRepository (Tomaj\NetteApi\Misc\StaticTokenRepository).

With this registration you will have api /api/v1/users that will be accessible from anywhere with Authorisation HTTP header Bearer dasfoihwet90hidsg or from 127.0.0.1 with Bearer asfoihweiohgwegi. In Nette-Api if you would like to specify IP restrictions for tokens you can use this patterns:

But it is very easy to implement your own Authorisation for API.

API keys

You can also use API keys for authorization. An API key is a token that a client provides when making API calls. The key can be sent in the query string, header or cookie. See examples below:

Rate limit

This library provides simple interface for API rate limit. All you need to do is implement this interface like in example below:

Then you have to register API to ApiDecider with Rate Limit

Javascript ajax calls (CORS - preflight OPTIONS calls)

If you need to call API via javascript ajax from other domains, you will need to prepare API for preflight calls with OPTIONS method. Nette-api is ready for this situation and you can choose if you want to enable pre-flight calls globally or you can register prepared prefligt handlers.

Globally enabled - every api endpoint will be available for preflight OPTIONS call:

Or you can register custom OPTIONS endpoints:

Logging

It is good practice to log you api access if you provide valuable information with your API. To enable logging you need to implement class with interface ApiLoggerInterface (Tomaj\NetteApi\Logger\ApiLoggerInterface) and register it as service in config.neon. It will be automatically wired and called after execution of all API requests.

CORS Security

If you need to iteract with your API with Javascript you will need to send correct CORS headers. ApiPresenter has property to set this headers. By default api will send header 'Access-Control-Allow-Origin' with value ''*. If you need to change it you can set property $corsHeader to values:

1. 'auto' - send back header Access-Control-Allow-Origin with domain that made request. It is not secure, but you can acces this api from other domains via AJAX
2. '' - send header with '' - this will work fine if you dont need to send cookies via ajax calls to api with jquery $.ajax with xhrFields: { withCredentials: true } settings
3. 'off' - will not send any CORS header
4. other - any other value will be send in Access-Control-Allow-Origin header

You can set this property in config.neon if you register ApiPresenter:

or if you extend ApiPresenter, than you can set it on your own presenter.

WEB console - API tester

Nette-Api contains 2 UI controls that can be used to validate you api. It will generate listing with all API calls and also auto generate form with all api params.

All components generate bootstrap html and can be styled with bootstrap css:

You have to create components in your controller:

Troubleshooting

If your apache server is runing on CGI or fastCGI script, $_SERVER['HTTP_AUTHORIZATION'] is empty. You'll need to do some mod_rewrite wizardry to get your headers past the CGI barrier, like so:

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

Contributing

Please see CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information