首页 > 主页 > tongfuapi
日志:17 评论:0
北京, 东城
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对象的准备工作就做好了,现在我们可以开始编写业务逻辑了!!!