README

这是另一个 Kohana 的 RESTful API 模块，它从 Kohana 3.1.1.1 的核心 REST 模块移植而来，并发展成为一个具有许多美好特性的更完整的解决方案。

该模块目前支持 Kohana 3.3。

我的榜样

特性

内置支持 GET/POST/PUT/DELETE HTTP 方法（其他方法可以轻松扩展）。
封装查询和表单参数解析。
多种输出格式 - JSON（包括 jsonp）、CSV、XML 和 HTML。
方法重写和响应代码抑制，适用于有限客户端。
多种可扩展的用户授权方法，内置 ACL 支持。
缓存控制。
附件头。
命令行支持，使用 Minion 任务。

示例模块

配套的示例模块可以安装，以获取对 RESTful 模块及其一些基本功能（如控制器、模型和用户类实现）的工作知识。

基本用法

在 Kohana::modules 中启用模块后，您必须为应用程序创建一个路由。

推荐的引导路由

Route::set('default', '<version>(/<directory>)/<controller>(.<format>)',
	array(
		'version' => 'v1',
		'format'  => '(json|xml|csv|html)',
	))
	->defaults(array(
		'format' => 'json',
	));

控制器

您的应用程序中的每个 REST 控制器都必须扩展 Controller_REST。然后，您的控制器将可以访问以下变量

$this->_params - 一个关联数组，包含请求中传递的所有参数，无论使用哪种方法。
$this->_user、$this->_auth_type 和 $this->_auth_source - 用户授权信息。有关更多信息，请参阅下面的用户授权部分。

可以实现以下操作函数以支持每个对应的 HTTP 方法

action_index() - 用于 GET 请求。
action_create() - 用于 POST 请求。
action_update() - 用于 PUT 请求。
action_delete() - 用于 DELETE 请求。

模型

您可以使用任何模型类，但如果您打算实现用户授权和 ACL，建议扩展 Model_RestAPI，它强制传递一个 RestUser 实例（有关更多信息，请参阅用户授权部分）。

视图

默认输出格式为 JSON，无需任何特殊视图。但是，该模块支持 HTML 输出格式，它依赖于视图来输出数据。

当请求的输出格式为 .html 时，模块会使用与请求相同的目录结构搜索相关的视图文件。例如，如果请求是 /path/to/object.html，则模块会搜索视图文件 /path/to/object.php。

通常以JSON格式返回的所有数据都可在视图文件中的变量$data中找到。

错误处理

该模块使用HTTP异常来管理错误。如果您想报告错误，例如错误的请求（400）、未经授权（401）等，您应该使用以下命令

$code = 400; // Or any other HTTP code.
$message = 'A positive integer value is expected'; // Free text.
$field = 'id'; // (Optional) The name of the field that produced an error.
throw HTTP_Exception::factory($code, array('error' => $message, 'field' => $field), array(), NULL);

用户授权

默认情况下，您的REST请求没有任何授权。

为了添加授权，必须采取以下步骤

扩展Kohana_RestUser类

RestUser类用于表示当前正在运行请求的用户。

该模块包含一个抽象的Kohana_RestUser类，您必须在该应用程序中扩展该类。唯一需要实现的是受保护的函数_find()。函数的实现预期将基于API密钥加载任何与用户相关的数据。

请阅读Kohana_RestUser中的各种代码注释以更好地理解此实现。如果有什么不清楚的地方，请与我联系。

控制器设置

您的应用程序中的每个控制器都可以实现不同类型和来源的授权。默认情况下，您的控制器的$_auth_type是关闭的（即没有授权）。

您应该将$_auth_type设置为以下之一以启用授权

RestUser::AUTH_TYPE_APIKEY - 用户必须通过API密钥。
RestUser::AUTH_TYPE_SECRET - 用户必须通过API密钥和另一个秘密密钥。
RestUser::AUTH_TYPE_HASH - 用户传递一个散列字符串签名。

您还应该将$_auth_source设置为以下之一以定义如何在请求中传输授权数据

RestUser::AUTH_SOURCE_GET - 期望在请求的查询参数中找到授权数据。
RestUser::AUTH_SOURCE_HEADER - 期望在请求的头中找到授权数据。
RestUser::AUTH_SOURCE_GET | RestUser::AUTH_SOURCE_HEADER - 可以使用GET或HEADER。

ACL配置（可选）

该模块支持本地ACL。

要使用此功能，您必须创建一个名为acl.php的配置文件。该文件必须返回一个关联数组，其中键是一个描述操作的任意字符串（例如，“创建redmine问题”），值是一个数组，列出了允许执行此操作的用户组（例如，array('manager', 'admin')）。

请注意，您将不得不在您的RestUser的_find()实现中加载您的用户组。

一旦设置，您就可以在控制器和模型中使用RestUser的函数can()和is_a()来授权不同的操作。例如

if (!$this->_user->can('create redmine issues'))
{
	throw HTTP_Exception::factory(401, array('error' => 'You cannot create issues'), array(), NULL);
}

if ($this->_user->is_a('manager'))
{
	// Do some extra stuff for managers.
}

特殊参数

以下特殊查询参数被支持

callback - 如果传递此参数，并且输出格式是JSON，则返回的数据以JSONP格式传递，因此数据将包裹在名为通过callback传递的值的函数中。
suppressResponseCodes - 一些客户端无法处理除200以外的HTTP响应。传递suppressResponseCodes=true将使响应始终返回200 OK，同时在响应体中附加真实的响应代码作为额外键。更多信息请参阅：[https://blog.apigee.com/detail/restful_api_design_tips_for_handling_exceptional_behavior](https://blog.apigee.com/detail/restful_api_design_tips_for_handling_exceptional_behavior)
method - 一些客户端无法设置除GET以外的HTTP方法。对于这些客户端，我们支持简单地将方法作为查询参数传递。method可以设置为POST、PUT、DELETE或您希望支持的任何其他方法。
attachment - 您可能有时希望允许用户通过直接链接从浏览器直接查询您的API并下载数据。在这种情况下，您可以添加此参数，其值代表文件名。这将使模块声明一个“content-disposition”头，使用户的浏览器打开下载窗口。

命令行

您可以使用CLI命令创建对REST API的请求。以下参数是预期的

headers - 请求的头部。
method - 请求的方法（GET、POST等）。
get - GET查询参数。
post - POST参数。
resource - 要发送请求的资源，通常表示为URL。

待办事项

将此README转换为Kohana指南。
编写测试。

合作者

非常感谢ozadi3，没有您我无法做到这一点！

该模块由SupersonicAds维护。

贡献

像往常一样，Fork并发送pull请求

获取帮助

联系我.
在此项目中打开问题。

alle / kohana-restful-api

维护者

详细信息