API

###

Note

此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以在 Mautic Developer Documentation archived repository 中访问它。

如果您有兴趣帮助开发此页面和其他新内容的，请考虑加入文档编写工作。

请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始您的贡献。

要添加自定义 API 接口，请在插件的配置文件 :doc:`Plugin’s config file</plugins/config> 中定义路由。 这会将路由置于 /api 之下，该路径仅授权用户可以访问。

<?php
// plugins/HelloWorldBundle/Config/config.php

declare(strict_types=1);

return [
    // ...

    'services' => [

        // ...

        'controllers' => [
            'plugin.hello_world.controller.api' => [
                'class' => \MauticPlugin\HelloWorldBundle\Controller\ApiController::class,
                'arguments' => [
                    'mautic.security',
                    'plugin.hello_world.model.worlds'
                ],
                'methodCalls' => [
                    'setContainer' => [
                        '@service_container',
                    ],
                ],
            ],
        ],
    ],

    'routes'   => [

        // ...

        'api' => [
            'plugin_helloworld_api' => [
                'path'       => '/hello/worlds',
                'controller' => 'HelloWorldBundle:Api:worlds',
                'method'     => 'GET'
            ]
        ]
    ],

    // ...
];

API 控制器应扩展 Mautic\ApiBundle\Controller\CommonApiController 以利用提供的辅助方法。

<?php
// plugins/HelloWorldBundle/Controller/ApiController.php

declare(strict_types=1);

namespace MauticPlugin\HelloWorldBundle\Controller;

use Mautic\ApiBundle\Controller\CommonApiController;
use Mautic\CoreBundle\Security\Permissions\CorePermissions;
use MauticPlugin\HelloWorldBundle\Model\WorldsModel;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class ApiController extends CommonApiController
{
    private CorePermissions $corePermissions;
    private WorldsModel     $worldsModel;

public function __construct(CorePermissions $corePermissions, WorldsModel $worldsModel)

{

$this->corePermissions = $corePermissions; $this->worldsModel = $worldsModel;

}

/** * Get a list of worlds */ public function getWorldsAction(Request $request): Response {

if (!$this->corePermissions->isGranted(‘plugin:helloWorld:worlds:view’)) {

return $this->accessDenied();

}

$filter = $request->query->get(‘filter’, null); $limit = $request->query->get(‘limit’, null); $start = $request->query->get(‘start’, null);

$worlds = $this->model->getWorlds($filter, $limit, $start); $worlds = $this->view($worlds, 200);

return $this->handleView($worlds);

}

}

API-aware entity locking

Mautic supports locking for API-editable entities, such as Emails, to prevent overwriting changes while a User is actively editing the entity in the UI.

This is useful to:

• Ensure the API respects the locking behavior already in place in the UI.

• Return a 409 Conflict when the system locks a record.

Enable API lock for a model

To make an entity model API-lock-aware:

1. Implement the interface:

   use Mautic\ApiBundle\Model\ApiLockAwareInterface;
   
   class MyEntityModel implements ApiLockAwareInterface
   {
      // ...
   }
   

2. Use the trait to reuse locking logic:

   use Mautic\ApiBundle\Model\ApiEntityLockTrait;
   
   class MyEntityModel implements ApiLockAwareInterface
   {
       use ApiEntityLockTrait;
   
       // Optional: Override `isApiLocked()` if you need custom behavior
   }
   

This ensures the API checks your model during editing.

Behind the scenes, the API controller validates:

if ($this->model instanceof ApiLockAwareInterface && $this->model->isApiLocked($entity)) {
    ....
}

Error message

If the API detects a locked entity, it returns:

{
  "errors": [
    {
      "message": "{Entity} is currently checked out by {User} (on {Date} at {Time}).",
      "code": 409,
      "details": {
        "checkedOutBy": "{User}",
        "checkedOut": "{Date} {Time}"
      }
    }
  ]
}

This format helps client apps identify locked records and avoid overwriting.