README

安装

composer require silverstripe/restfulserver

概述

这个类为您的应用程序提供了一个 RESTful API。您只需将适当的 DataObjects 上的 api_access 配置选项设置为 true。您需要确保所有数据操作和安全都在您的模型层（即 DataObject 类）中定义，而不是在您的控制器中。这是 SilverStripe 应用的推荐设计。

配置

具有简单 API 访问的示例 DataObject，除非通过模型权限显式控制，否则将完全访问所有对象属性和关系。

namespace Vendor\Project;

use SilverStripe\ORM\DataObject;

class Article extends DataObject {

	private static $db = [
        'Title'=>'Text',
        'Published'=>'Boolean'
    ];

	private static $api_access = true;
}

具有高级 API 访问的示例 DataObject，仅限制查看和编辑到 Title 属性。

namespace Vendor\Project;

use SilverStripe\ORM\DataObject;

class Article extends DataObject {

    private static $db = [
        'Title'=>'Text',
        'Published'=>'Boolean'
    ];

    private static $api_access = [
        'view' => ['Title'],
        'edit' => ['Title']
    ];
}

示例 DataObject 字段映射，允许别名字段，以便公开请求和响应显示不同的字段名。

namespace Vendor\Project;

use SilverStripe\ORM\DataObject;

class Article extends DataObject {

    private static $db = [
        'Title'=>'Text',
        'Published'=>'Boolean'
    ];

    private static $api_access = [
        'view' => ['Title', 'Content'],
    ];

    private static $api_field_mapping = [
        'customTitle' => 'Title',
    ];
}

给定一个具有值的 dataobject

    ID: 12
    Title: Title Value
    Content: Content value

当通过 URL /api/v1/Vendor-Project-Article/12?fields=customTitle,Content 和 Accept: application/json 请求时，响应将如下所示

{
    "customTitle": "Title Value",
    "Content": "Content value"
}

类似地，PUT 或 POST 请求将具有从别名名称转换为数据库字段名称的字段转换。

支持的操作

• GET /api/v1/(ClassName)/(ID) - 获取数据库记录

• GET /api/v1/(ClassName)/(ID)/(Relation) - 获取通过给定关系链接到该数据库记录的所有记录

• GET /api/v1/(ClassName)?(Field)=(Val)&(Field)=(Val) - 搜索匹配的数据库记录

• POST /api/v1/(ClassName) - 创建新的数据库记录

• PUT /api/v1/(ClassName)/(ID) - 更新数据库记录

• PUT /api/v1/(ClassName)/(ID)/(Relation) - 更新关系，替换现有记录（尚未实现）

• POST /api/v1/(ClassName)/(ID)/(Relation) - 更新关系，追加到现有记录（尚未实现）

• DELETE /api/v1/(ClassName)/(ID) - 删除数据库记录（尚未实现）

• DELETE /api/v1/(ClassName)/(ID)/(Relation)/(ForeignID) - 移除两个数据库记录之间的关系，但实际上不删除外部对象（尚未实现）

• POST /api/v1/(ClassName)/(ID)/(MethodName) - 在给定的对象上执行方法（例如发布）

搜索

您可以根据在 DataObject::searchable_fields 上指定的字段以及通过 DataObject::getDefaultSearchContext() 传递的字段触发搜索。只需将搜索词添加到 URL 中的键值对，例如 /api/v1/(ClassName)/?Title=mytitle。

其他 URL 修改器

• &limit=<numeric>: 限制结果集
• &relationdepth=<numeric>: 显示指向现有 has-one 和 has-many 关系的链接，深度为一定深度（默认值：1）
• &fields=<string>: 输出对象上的字段列表（默认为所有数据库列）。对于带宽和性能原因，非常有用，可以限制输出。
• &sort=<myfield>&dir=<asc|desc>
• &add_fields=<string>: 附加字段列表，例如动态获取器。

访问控制

通过通常的 Member 系统实现访问控制，仅使用 BasicAuth 认证。默认情况下，您必须具有 ADMIN 权限才能检索或发送任何数据。您应重写以下内置方法以自定义类和对象级别的权限控制

• DataObject::canView()
• DataObject::canEdit()
• DataObject::canDelete()
• DataObject::canCreate()

有关详细信息，请参阅 SilverStripe\ORM\DataObject 文档。

您可以在HTTP Content-Type中指定任何输入的字符编码。目前，只支持UTF-8。所有输出都使用UTF-8编码，不管Accept头如何。