Custom API actions¶
Routing¶
You can define a specific route to access your api action.
Default routes are defined here application/Espo/Resources/routes.json
.
Custom routes can be defined in following places:
application/Espo/Modules/{moduleName}/Resources/routes.json
custom/Espo/Custom/Resources/routes.json
Example¶
routes.json
[
{
"route": "/Hello/test/:id",
"method": "get",
"params": {
"controller": "MyController",
"action": "doSomething",
"id": ":id"
}
},
{
"route": "/HelloWorld/:name",
"method": "post",
"params": {
"controller": "MyController",
"action": "helloWorld",
"name": ":name"
}
},
{
"route": "/TestNoAuth",
"method": "get",
"params": {
"controller": "Test",
"action": "test"
},
"noAuth": true
}
]
The parameter noAuth
allows making requests w/o authentication.
Controller:
<?php
namespace Espo\Custom\Controllers;
use Espo\Core\Api\Request;
use Espo\Core\Api\Response;
class MyController
{
private $someDependency;
public function __construct(SomeDependency $someDependency)
{
$this->someDependency = $someDependency;
}
public function getActionDoSomething(Request $request, Response $response): void
{
$id = $request->getRouteParam('id'); // '001'
// Assuming the request GET api/v1/Hello/test/001 has been sent,
// a route parameter 'id' will equal '001'.
$response->writeBody(
json_encode($someData)
);
// You can either write data to the response or use return
// Returned value will be encoded and written to the reponse.
}
public function postActionHelloWrold(Request $request, Response $response): void
{
$name = $request->getRouteParam('name');
// Assuming the request POST api/v1/HelloWorld/someName has been sent,
// a route parameter 'name' will equal 'someName'.
$response->writeBody('true');
}
}
You need to clear cache after changes.
Extending existing controller¶
Example for Account scope.
Create a file (or modify if it already exists) custom/Espo/Custom/Controllers/Account.php
.
<?php
namespace Espo\Custom\Controllers;
use Espo\Core\Api\Request;
use Espo\Core\Api\Response;
class Account extends \Espo\Modules\Crm\Controllers\Account
{
/**
* POST api/v1/Account/action/test
*/
public function postActionTest(Request $request, Response $response): bool
{
$someParam = $request->getQueryParam('someParam'); // GET parameter
$data = $request->getParsedBody(); // payload
$someValue = $data->someKey ?? null;
$response->setStatus(201); // example how to set custom response status code
// call some service class here
return $someData; // can be true, false, array or object.
}
/**
* GET api/v1/Account/action/test
*/
public function getActionTest(Request $request, Response $response): void
{
$someParam = $request->getQueryParam('someParam'); // GET parameter
// call some service class here
$response->writeBody('true');
}
}
Note: For Account entity type we extend Espo\Modules\Crm\Controllers\Account
. Some entity types might not have controllers in Espo\Modules\Crm\Controllers
namespace. They are defined in Espo\Controllers
namespace.
Custom controller¶
In Custom folder¶
Create a file custom/Espo/Custom/Controllers/MyController.php
.
<?php
namespace Espo\Custom\Controllers;
class MyController
{
}
Clear cache (Administration > Clear Cache).
In Module folder¶
Create a file custom/Espo/Modules/MyModule/Resources/metadata/scopes/MyController.json
.
{
"module": "MyModule"
}
Create a file custom/Espo/Modules/MyModule/Controllers/MyController.php
.
<?php
namespace Espo\Modules\MyModule\Controllers;
class MyController
{
// Dependencies are passed to the constructor.
}
Clear cache (Administration > Clear Cache).
CRUD actions¶
<?php
namespace Espo\Custom\Controllers;
use Espo\Core\Api\Request;
use Espo\Core\Api\Response;
class MyController
{
// Creates a record.
public function postActionCreate(Request $request, Response $response)
{
}
// Reads a record.
public function getActionRead(Request $request, Response $response)
{
}
// Updates a record.
public function putActionUpdate(Request $request, Response $response)
{
}
// Deletes a record.
public function deleteActionDelete(Request $request, Response $response)
{
}
}
Custom controller¶
Example:
<?php
namespace Espo\Modules\MyModule\Controllers;
use Espo\Core\Api\Request;
use Espo\Core\Api\Response;
use SomeDependency;
use stdClass;
class MyController
{
private $someDependency;
public function __construct(SomeDependency $someDependency)
{
$this->someDependency = $someDependency;
}
public function putActionUpdate(Request $request, Response $response): stdClass
{
$id = $request->getRouteParam('id');
$data = $request->getParsedBody();
$result = $this->someDependency->doSomething($id, $data);
// Response can be returned or written with `Response::writeBody`.
return $result->toStdClass();
}
}