TFAPI的RESTFul接口开发手册V1.0

1. 搭建RESTFul环境

• 建立一个目录用于作为RESTFul风格的API接口的根目录，此目录可以用作网站的根目录使用，我们称之为——API根目录

• 复制框架 sample/api/ 下的 RESTFul.php 和 .htaccess 两个文件到第一步建立的API根目录下

• 修改 RESTFul.php 的数据源为你自己环境的数据源，默认为 sample

• 修改 RESTFul.php 的包含文件，初始化等部分的代码

• 至此准备工作就做好了

2. 建立基于RESTFul接口的功能对象

• 使用框架 common.common_webservice 目录下的 common_service 里面的 tf_webservice_process 对象作为自己的功能对象的基类，该对象构造函数会将 $dbObj 和 $pageObj 引用进来

• 建立自己的功能对象，文件名称必须是 [类名称].class.php，类名称必须以 tf_webservice_process_ 开头，继承 tf_webservice_process 基类，以下是示例代码：

// 文件名称 myClass.class.php:
// 类名称 tf_webservice_process_myClass

using('myClass_action');

class tf_webservice_process_myClass extends tf_webservice_process{
    public function myFunction(){
        // $this->dbObj, $this->pageObj 可以直接访问到
    }
    public function mySub(){
        return 123;
    }
}

• 在功能对象里增加RESTFul的四个标准公开GET、POST、PUT、DELETE方法，代码如下：

// $methodName - GET, POST, PUT, DELETE
// $arguments - 我们传递的数据参数
// $argumentDataFormat - 默认json，可选为：json, xml, php, text。其中 php 就是 serialize 编码的方式，text 就是不进行编码的方式

class tf_webservice_process_myClass extends tf_webservice_process{
    public function getRESTFul(){
         
    }
    public function postRESTFul(){
         
    }
    public function putRESTFul(){
         
    }
    public function deleteRESTFul(){
         
    }
}

• 这样设置之后我们的 myClass 对象就可以被通过 RESTFul 规范的接口方式访问到了

3. RESTFul接口环境下的四个变量介绍

• 第一个变量 $this->RESTFul_Argv，资源变量。这个变量来源于 RESTFul 资源路径上面的参数。

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'dataFormat'=>"json",
    ));
$userInfo = $myRESTFulObj->doAction("http://localhost/api/user/info/1", "GET"); // 这里的 Argv 变量则为 array(0=>"user", 1=>"info", 2=>1)

• 第二个变量 $this->RESTFul_Header，头信息变量。这个变量来源于 RESTFul 客户端请求时候在HTTP头信息里携带的参数。

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'dataFormat'=>"json",
    ));
$userInfo = $myRESTFulObj->doAction("http://localhost/api/user/info/1", "GET", null, array('Authorization: myUser myPwd')); // 这里的 Header 变量则为 array("Authorization"=>"myUser myPwd")

• 第三个变量 $this->RESTFul_Param，参数变量。这个变量来源于 RESTFul 资源路径的 QUERY_STRING。

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'dataFormat'=>"json",
    ));
$userInfo = $myRESTFulObj->doAction("http://localhost/api/user/info/1?bc=utf8", "GET"); // 这里的 Param 变量则为 array("bc"=>"utf8")

• 第四个变量 $this->RESTFul_Post，提交变量。这个变量来源于 RESTFul 客户端请求的 RAW 数据。需要注意的是 Post 变量只有在请求方法为 POST 或者 PUT 的情况下才会生效。

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'dataFormat'=>"json",
    ));
$userInfo = $myRESTFulObj->doAction("http://localhost/api/user/info/1", "POST", array('key1'=>"val1", 'key2'=>"val2")); // 这里的 Post 变量则为 array("key1"=>"val1", "key2"=>"val2")

• 下面是一个携带所有四种变量的例子。

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'dataFormat'=>"json",
    ));
$userInfo = $myRESTFulObj->doAction("http://localhost/api/user/info/1?bc=utf8", "POST", array('key1'=>"val1", 'key2'=>"val2"), array('Authorization: myUser myPwd'));

4. 注册功能对象到RESTFul接口环境下

• 路由程序 RESTFul.php 的寻址方式是：首先从当前目录下查询类文件是否存在，如果不存在则会尝试在上一级目录的 webservices 子目录下查找。具体如下：

// 假设 RESTFul.php 路由程序部署在 /var/www/api/ 下，我们试图访问资源 user，则路由程序查询的顺序为
// 第一次查找的目录为 %{TFAPI_RESURL_PATH_ROOT}var/www/api/user.class.php
// 第二次查找的目录为 %{TFAPI_RESURL_PATH_ROOT}var/www/webservices/user.class.php

• 也就是说我们需要保证在以上的两个目录为止的任意一个位置可以找到目标类文件，才可以保证功能可以被正常访问

5. 调用基于RESTFul接口的功能

• 调用RESTFul接口有几个规范，我们逐一说明一下：

• 首先，我们需要确定本次访问的资源是什么，例如：我们想获得一个用户的个人信息，则其资源就是user，具体用户ID则作为资源的具体描述。示例：

// 我们的功能对象最后可以得到一个 GET 方法的请求，其参数为 [user] [1]，我们可以根据这个进行具体功能的处理

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'inputDataFormat'=>"json",
    ));
$userInfo = $myRESTFulObj->doAction("http://localhost/api/user/1", "GET");

• 其次，如果我们需要对资源进行一个更新的操作，则我们需要像资源提供更多的参数。示例：

$myRESTFulObj = new tf_restful_client($this->pageObj, array(
        'inputDataFormat'=>"json",
    ));
$ret = $myRESTFulObj->doAction("http://localhost/api/user/", "PUT",
        array(
            'userName'=>"tongfu", 'userPwd'=>"123456" // Post数据，一般是表单 POST 过来的数据
        ),
        array(
            'Authorization: my auth data' // Header数据，自定义HTTP头信息数据
        )
    );
5. 调用第三方RESTFul接口的范例