TFAPI的RESTFul接口开发手册V1.2（示例讲解）

使用TFAPI框架开发RESTFul API接口只需要如下几个步骤：


1）选择一个API的根目录
这个目录必须是专门用来做RESTFul API使用的，不能有其他内容存在，因为我们会使用rewrite技术对改目录下的内容进行自由路由管理。

常用的接口路径位置有：

• 项目根目录/api/

• 项目根目录/restful/

然后我们将框架的sample目录下的restful子目录里面的所有内容都复制到刚刚选择的API的根目录里。

包含的文件有：

• .htaccess

• .root.php

• RESTFul.php

2）建立API对象文件
首先，我们根据一个资源（resource）一个API对象的原则先定义好我们的资源的名称，例如：users。
接着，这个API对象文件的存放位置以及命名规则都有要求。

可以选择的位置以及对应的命名规则为：

• API根目录/[资源名称].class.php

• API根目录/../api/[资源名称].class.php

• API根目录/../webservices/[资源名称].class.php

• 项目WEB-APP的classes目录/interface_classes/[资源名称].inc.php

3）编写API对象
API对象的设计遵循以下规则即可，具体规则如下：

• 对象类名称必须是tf_webservice_process_[资源名称]

• 对象类必须继承tf_webservice_process类，或者是扩展于这个tf_webservice_process类的其他类

• 对象类需要重载四个基础方法：getRESTFul，putRESTFul，deleteRESTFul，postRESTFul

• 四个基础方法必须使用getRESTFulResult($statusCode, $resultArr, $statusMsg)作为返回值

• 如果指定资源数据不存在，需要使用getRESTFulResult(404)作为返回值

• 如果指定资源操作失败，需要使用getRESTFulResult(500)作为返回值

• 其他情况，请使用getRESTFulResult(200)作为返回值

• 我们可以using其他模型对象，或者include其他对象来完成我们的API对象业务逻辑
  

我们以users作为资源名称写的一个示例：

using('users_action');

class tf_webservice_process_users extends tf_webservice_process {
/**
 * RESTFul styles
 *
 */
public function getRESTFul(){
return $this->getRESTFulResult(200, array());
}
public function postRESTFul(){
return $this->getRESTFulResult(200, array());
}
public function putRESTFul(){
return $this->getRESTFulResult(200, array());
}
public function deleteRESTFul(){
return $this->getRESTFulResult(200, array());
}
}

4）API对象的认证功能使用
如果要开启API对象的认证功能，则需要单独制作一个用来实现认证的对象作为API对象的父类对象，该对象需要重载两个方法：

• authorization 用来实现接口的认证逻辑

• authorize__failed 用来设置认证失败时候的消息处理（可选）

以下是一个认证对象的示例代码：

class tf_webservice_process_auth extends tf_webservice_process {
public function authorize__failed(){
return array('errcode'=>100011,'errmsg'=>'Access Denied');
}
public function authorization(){
return ($this->pageObj->server->HTTP_AUTH_USER == "demo" && $this->pageObj->server->HTTP_AUTH_PW == "123456");
}
}

如果要实现OAuth2.0之类的复杂认证模式，则需要开发更多的代码。
我们将会在下一节讲解如何使用OAuth2.0认证我们的API对象。

5）RESTFul.php的EndPoints设定
打开RESTFul.php文件，找到如下位置，进行EndPoints的设定：

class RESTFul_page {
protected $dbObj;
protected $pageObj;
public function __construct($dbObj, $pageObj){
$this->dbObj = $dbObj;
$this->pageObj = $pageObj;
}
public function process(){
$gvs = $this->pageObj->get;
// here coding statement

// start service
$myRESTFulRouterObj = new tfapi_restful_router($this->dbObj, $this->pageObj);
$myRESTFulRouterObj->mapRoute(array(
'endPoints'=>array(
"v1/class/{id}/news",
"v1/class",
),
));
$myRESTFulRouterObj->startRoute( tfapi_restful_route_mode::T_MODE_CONFIG );
}
}

设定EndPoints的注意事项：

• 把startRoute方法里传递的参数改成tfapi_restful_route_mode::T_MODE_CONFIG

• 通过mapRoute方法设置EndPoints，可以设置多个endPoint模板

• 有层级关系的endPoint要把小集合放在前面

• 可以通过paramName/paramValue/paramName2/paramValue2/...的格式向资源传递多个限定参数，这些参数最终会变成GET参数传递给API对象

至此，我们的API对象的准备工作就做好了，现在我们可以开始编写业务逻辑了！！！