Action
The action contains the logic to handle the request and produce a response. Each action is based on a class and can have specific parameters. Canpi contains already some actions for common tasks i.e. to execute database operations or push data to a message queue.New Article
Development
To develop a custom action you need to create a class which implements the interface Canpi\Engine\ActionInterface. Then you can add this class to the provider.php file. Thus it is possible to select this action at the backend. Please take a look at the src/ folder for more examples.
App
An app enables the consumer to request an access token through the app key and secret. With the access token it is possible to request protected API endpoints. There is a default consumer implementation located at developer/ which enables a user to manage their apps. The consumer can use any OAuth2 client to request an access token. Canpi supports by default the authorization_code, implicit and password grant type. Please take a look at the OAuth2 RFC for more information about the flow.
Authorization code
At first you have to redirect the client to the consumer endpoint containing the app key, redirect uri and the needed scopes i.e.: /developer/auth?response_type=code&client_id=[key]&redirect_uri=[url]&scope=foo,bar. After the user has authenticated he approves or denies the access. If he accepts the user gets redirected to the provided redirect_uri. Note the redirect_uri must have the same host as the url which was provided for the app. The callback contains a GET parameter code which can be exchanged for an access token at the /authorization/token endpoint.
Implicit
Mostly used for javascript apps. Like in the authorization code flow the app redirects the user to the consumer endpoint i.e.: /developer/auth?response_type=token&client_id=[key]&redirect_uri=[url]&scope=foo,bar If the user has authenticated and approved the app the user gets redirected to the redirect_uri. The callback contains the access token in the fragment component. The access tokens which are issued through the implicit grant have usually a much shorter life time because they are more insecure. It is also possible to deactivate the implicit grant through the configuration.
Password
A user can use the password grant to obtain directly an access token with their username and password. Therefor he has to send a direct request to the /authorization/token endpoint.
Config
The config contains system wide settings. In the following we explain some important settings which you most likely need to configure.
- mail_register_bodyIf a new user registers through the consumer app he receives an activation mail. Through this setting you can configure the text and adjust the activtaion url
- recaptcha_secretIf provided the consumer registration can show an google recaptcha which prevents automatic registration. You also have to provide the recaptcha public key to the consumer app
- scopes_defaultThose are the scopes which are assigned by default if a new user registers
- provider_facebook_secret provider_github_secret provider_google_secretIf provided a user can login through those remote providers. You also have to provide the app key to the consumer app
Connection
A connection enables Canpi to connect to other remote sources. This can be i.e. a database or message queue server. Please take a look at the adapter to see a list of all available connections. It is also easy possible to develop your own custom connection.
Development
To develop a custom connection you need to create a class which implements the interface Canpi\Engine\ConnectionInterface. Then you can add this class to the provider.php file. Thus it is possible to select this connection at the backend.
Cronjob
When building an API it is sometimes required that specific code gets executed at a certain interval. For this purpose Canpi provides the cronjobs.
To execute those cronjobs Canpi uses the standard linux cron util. It can write a dedicated cron file which contains all needed cron entries. This file should be placed in the cron.d folder of your system.
Installation
To tell Canpi that it should write such a cron file you need to create the file where the Canpi_cron_file setting points to i.e. /etc/cron.d/canpi. The web user needs also write access to this file since Canpi always updates the file in case you create or update an entry. You can change those settings at the configuration.php file.
Error
Lists all errors which occurred on the endpoints. The detail view shows the message and the stack trace of the error.
Event
Canpi has an event system which helps to build a pub/sub system. This means consumer of your API can subscribe to specific events. Inside your API endpoint you can then trigger such an event. Canpi will then send the payload to each subscriber in the background.
Installation
To enable Canpi to send messages in the background you need to setup a cronjob which executes the HTTP requests. The cronjob must execute the event:execute command i.e.:
| php /bin/canpi event:execute |
Subscribe
To subscribe for such an event the user needs to send a HTTP POST request to the /consumer/subscription endpoint with the following payload:
{
"event": "my_event",
"endpoint": "http://my-app.com/callback"
}
|
Publish
To publish an event you need to use the dispatcher to create an event. I.e. the following action shows how to dispatch data to the event my_event which then will send the provided data JSON encoded to the subscribed endpoints.
<?php
namespace App\Todo;
use Canpi\Engine\ActionAbstract;
use Canpi\Engine\ContextInterface;
use Canpi\Engine\ParametersInterface;
use Canpi\Engine\RequestInterface;
class Collection extends ActionAbstract
{
public function handle(RequestInterface $request, ParametersInterface $configuration, ContextInterface $context)
{
// dispatch my event
$this->dispatcher->dispatch('my_event', [
'foo' => 'bar'
]);
}
}
|
Callback
Canpi will send the following HTTP POST request to every subscribed endpoint. In case the endpoint returns a non successful status code Canpi will try to resend the message up to 3 times.
POST /callback HTTP/1.1
Host: my-app.com
Content-Type: application/json
User-Agent: Canpi/4.0.2@916a81045349cc0e149873b5b794777bb5f29a30
{"foo": "bar"}
|
Import
The importer provides a way to import route and schema definitions. The data must be in the OpenAPI, RAML or Swagger format. The importer displays a preview what data is imported before any changes are made
Plan
A plan can be purchased by a user to obtain points. Those points can then be used to call specific API endpoints. At the backend it is possible to set a specific cost for each route. Every plan has a name, description, price and points. The developer app contains already a possibility to buy those plans.
To enable payments you need to setup a payment provider (i.e. paypal). Through the payment provider the user can purchase such plans. Please take a look at the manual to see how to setup a payment provider:
Rate
Through a rate it is possible to limit the amount of incoming requests to a threshold. If the threshold is reached the user receives a 429 HTTP status code. A rate can distinguish between authenticated and not authenticated calls. For authenticated calls the request count is based on the app for not authenticated calls it is based on the ip address.
Scope
A scope describes the right to access specific routes and request methods. Each user account has assigned a set of allowed scopes. If a user creates an app he can only assign the scopes which are available for him.
User
A user is either a Consumer which uses the API or an Administrator which manages the API through the backend. An Administrator account can request an access token for the backend API. Canpi has a simple consumer app located at /developer where a user can manage all app settings.