Pluginable API allow 3rd party developers to add and extend BillRun API.
API call to trigger pluginable API - http://host/plugins/{plugin}/{action}/{id}
API must implement the method (action) that is triggered. The plugin method name should be api{Action}, while the action name is with first character of string capitalised.
The url params as follow:
- {plugin} - the plugin name
- {action} - the action name. Recommend action names are CRUD: create, read, update, delete.
- {id} - optional. relevant only for read, update and delete.
standard request is supported and one of the input of the plugin method triggered by the API.
The plugin method input:
- $params - the url params (as mentioned above).
- $request - the http request (GET + POST).
- $response - response object to be able to define http response (including headers).
- Sample plugins function names convention are: apiCreate, apiRead, apiUpdate and apiDelete.
- Action name should be the name of the api function without the ‘api’. For example, for function 'apiDownloadinvoice’ in the plugin FoobarPlugin, the action will be ‘downloadinvoice’ and the API call to trigger: http://host/plugins/foobar/downloadinvoice/
- MUST HAVE! When implementing pluginable API, you should first check if the plugin is called by the API. Therefore, under the beginning of the plugin method, It should looks like this:
if ($params['plugin'] != $this->getName()) {
return;
}
If you're running under multi-tenant environment, need to verify the tenant (if required to run on one tenant only):
if ($params['plugin'] != $this->getName() && Billrun_Factory::config()->getTenant() != 'tenantname') {
return;
}
Without this check, any plugin that used pluginable API can trigger the method and in all tenants.
- Because there is check about the name (previous note), you should add property of the $name (protected) to the plugin class. See here example on webhooks plugins.
- The function name is according to the action in the request.
- Plugin does not have to implement all CRUD actions and it does not have to be CRUD. For example, action can be foo so the plugin method should be called apiFoo.
- Example can be found in webhooks plugin.