README

由co-stack.com提供支持

关于

此TYPO3扩展为TYPO3添加了通用的API功能。此扩展的强大之处在于它与TYPO3本身的集成以及它被其他扩展使用的简便性。如果您想在TYPO3中创建快速安全的API，应该使用此扩展。

如果没有安装其他需要此扩展的扩展，安装此扩展没有意义。

功能

基于可扩展的PSR-15请求中间件栈。
早期入口点：尽可能早地执行API目标。
前端入口点：在TYPO3前端启动后执行API目标。TypoScript等可用。
自动将响应格式化为XML、JSON、CSV等。

使用方法

使用EXT:api创建API端点是简单快捷的。以下步骤需要安装EXT:api和您的扩展。

创建您的API端点类。它可以在任何地方，但将其放在Classes/Api中是一个好习惯。根据其用途命名您的类。（例如：Vendor\Packaga\Api\VersionApi）。您的API类必须实现接口\CoStack\Api\Api\Api。最初返回一个包含一些值的数组。
在Configuration/Api.php中创建您的API注册文件并注册您的API类。该文件必须返回一个关联数组。关联索引是ROUTE，或API端点名称，将成为URL的一部分。以下是一个使用StatusApi类的示例。
```
 return [
    'status' => [
        'class' => \CoStack\Api\Api\StatusApi::class,
    ],
 ];
```
以管理员身份登录到您的TYPO3后端。转到根页面（ID 0）并选择列表模块。创建一个新的API令牌。您注册的API类应该显示在API作用域列表中。为您的令牌命名并添加您的API端点到API作用域列表中。保存令牌以生成令牌的密钥。
您可以使用curl测试您的API。将SECRET、DOMAIN、EXTKEY和ROUTE替换为您自己的值：\ curl -H "Accept: application/json" -H "X-T3API-TOKEN: <SECRET>" https://<DOMAIN>/api/<EXTKEY>/<ROUTE>\ 示例：curl -H "Accept: application/json" -H "X-T3API-TOKEN: a220d5a473232e636f845e0f6919981a1baf13e97758d83b2bde7c5ec68954b7" https://local.myproject.de/api/api/status 您应该看到JSON编码的数组。（从EXT:api 3.0开始，您也可以使用GET参数token代替X-T3API-TOKEN头）

高级用法

自动响应格式化

完整文档：ResponseFormatting.md

EXT:api试图确定请求了哪种内容类型，并据此格式化响应。这样可以节省您识别和格式化响应的部分。

如果您请求 /api/api/status.xml，您将收到XML格式的响应；如果请求 /api/api/status.json，您将获得JSON字符串格式的响应。在不带文件扩展名的情况下调用API /api/api/status，仍然可以发送一个包含优先级较高的MIME类型列表的 Accept 头部。 (您的浏览器通常发送类似 text/html,application/xml;q=0.9,*/*;q=0.8 的内容)。EXT:api 将尝试找到最高优先级的MIME类型的格式化器来格式化响应。如果没有提供 Accept 头部，则使用为API配置的MIME类型。

额外的中间件

完整文档：[Middlewares.md](https://gitlab.com/co-stack.com/co-stack.com/typo3-extensions/api/-/blob/HEAD/Documentation/Middlewares.md)

EXT:api中间件栈是完全可配置的。在 Configuration/RequestMiddlewares.php 中注册您自己的中间件。

<?php

return [
    'api' => [
        'vendor/ext/request/logger' => [
            'target' => \Vendor\Ext\Middleware\Api\Logger::class,
            'before' => [
                'co-stack/api/router',
            ],
        ],
    ],
];

API路由配置

完整文档：[ApiRoutes.md](https://gitlab.com/co-stack.com/co-stack.com/typo3-extensions/api/-/blob/HEAD/Documentation/ApiRoutes.md)

创建API非常简单。在您的扩展中创建 Configuration/Api.php 文件并注册您的API。

<?php

declare(strict_types=1);

return [
    'v1/extension/version' => [
        'class' => \CoStack\Api\Api\ExtensionVersionApi::class,
    ],
];

将 EXT_KEY 替换为您扩展的扩展键。

调用API：https://host.tld/api/EXT_KEY/v1/extension/version

调试

为了开发和调试您的API调用，您应该将TYPO3的 displayErrors 设置为 1 以进行本地开发。在公共或生产环境中，displayErrors 应该是 -1，并且您的 devIPmask 应该被设置。启用此设置将显示异常而不是静默失败。

curl

如果发生错误，您的API响应可能为空。您可以在curl调用中添加以下选项以获取更多信息

-I：显示响应头部（如果看不到任何响应，特别有用）。
-H "X-T3API-SAPI: cli"：强制在CLI中渲染异常。

目前实现了以下HTTP状态码

403：您未包含认证头部（X-T3API-TOKEN）或提供的密钥不正确。
406：您未在请求中包含 accept 头部或接受的MIME类型不受支持。始终先用 application/json 尝试。
429：您触发了硬限制。在扩展设置中增加每分钟的请求数。您可以将其设置为 0 来禁用速率限制器，但您必须意识到安全影响（例如DoS）。
500：您的API类中发生了异常。检查日志。

PhpStorm

如果您从API调用中未获得预期的结果，您可以使用xDebug和PhpStorm来调试请求。

如果您对xDebug或PhpStorm有任何问题，请使用互联网搜索。我们不会回答有关这些主题的询问。

创建一个新的.http scratch文件。将 SECRET、DOMAIN、EXTKEY 和 ROUTE 替换为您自己的值）
```
 https://<DOMAIN>/api/<EXTKEY>/<ROUTE>
 Accept: application/json
 X-T3API-TOKEN: <SECRET>
```
在 \CoStack\Api\Middleware\Frontend\EarlyApiMiddleware::process 中设置一个断点。
点击URL左侧的绿色箭头，选择PHP Debug。
如果您的项目设置正确，它应该触发您的断点。

co-stack / api

维护者

详细信息