Download the PHP package flame/tiny-rest without Composer

Nette REST library

Smart and tiny implementation of REST API for Nette framework

Content

1. Requirements
2. Installation
3. Configuration
4. Authentication
5. Routing and presenters
6. Examples
7. Patrons

Requirements

For full requirements list please see this file

• PHP 5.4 or higher
• Nette Framework 2.1 or higher

Installation

The best way to install flame\tiny-rest is using Composer

and register extension:

Configuration

This package provide next options:

• authenticators - list of classes implements Flame\Rest\Security\IAuthenticator for authentication requests.
• cors - List of settings for cross-domain requests
  • origin - list of allowed origins, or * for all
  • headers - list of allowed headers, or * for all
  • methods - list of allowed methods, or * for all
• ips - list of allowed IP address, or nothing for allow all
• referers - list of allowed referers, or nothing for allow all

Example configuration:

Authentication

This package provide several authorization method.

1. Authorization by IP address - this authorization is enabled automatically when you set ips option in config file.
2. Authorization by HTTP referer - this authorization is enabled automatically when you set referers option in config file
3. Authentication by settings for cross-domain requests - this authorization is automatically enabled when you set cors option in config file and respects this rules

Next authorization methods is token-based authorization. For this authorization type you must do some steps:

1. You can create own authenticator implements Flame\Rest\Security\IAuthenticator or you can use default authenticator from this package
2. You must create own token provider class implements Flame\Rest\Security\Tokens\ITokenProvider. This class with getToken() must get token from request (request is provided as argument) and create and return a new instance of Flame\Rest\Security\Tokens\IToken (there you must create own implementation or you can use default)
3. You must create own implementation of Flame\Rest\Security\Tokens\ITokenManager wḧich provides method for validate token and getting identity for concrete token.

Implementation you can see in Examples.

Routing and presenters

Routing

This package provides one basic route:

This route has one optional argument with module path for searching presenter. In this example expects models with names Api and V1.

Structure of URLs which is created by this router is /<module>/<presenter>[/<specific_action>][/<id>]. For our example will be /api/v1/<presenter>[/<specific_action>][/<id>]

All this URLs is mapped to actions in presenter by rule action<create|update|read|readAll|delete><specific_action>(<id>) when POST = create, PUT = update, DELETE = delete, GET without id = readAll and GET with id = read. For example:

• GET /api/v1/accounts -> actionReadAll()
• GET /api/v1/accounts/1 -> actionRead($id)
• GET /api/v1/accounts/disabled/1 -> actionReadDisabled($id)

Presenter

All API presenters should be extended from RestPresenter. When you can send data you must it write into resource:

or for better works you can use data property of resource

Sending responses is automatically on end of action method with HTTP code 200. When you can change it, you must call sendResource($code) manually.

And for processing and logging errors you can use sendErrorResponse method.

You can get data from POST, or query by input or getInput() member. You can get query values by getQuery(), POST values by getData() or FILES by getFiles()

Examples

Router:

Presenter AccountsPresenter.php

Create own Token implementation:

Create a own TokenGetter:

Create own TokenManager

In this example when I send GET request on /api/v1/accounts with Authorization: valid header and use BasicAuthenticator for authenticate by @User annotation API returns identity of logged user.

Patrons

Big thanks to these guys!

• Ondra Zaruba (aka @budry)