README

类似Web服务的引导

目标

提供轻量级的引导/框架，用于REST-like Web服务/JSON API。

REST-like 哲学

假设你想处理博客文章。

你需要提供 getPost() 请求和 putPost() 请求。你可能还会有 addComment() 请求。但最终，这三个请求可能都会返回 Post 对象...

使用 RLW，你可以定义主 post() 请求并添加子请求：put() 和 addComment()。

RLW 管理请求的依赖关系。因此，如果 Post 不存在，子请求将被取消。

副作用之一是节省一些 HTTP 请求：你可以在一个请求中“打包”许多操作。

引导

./foo 文件夹展示了一个基本的 Web 服务（与 PHPUnit 测试一起使用）。

Web 服务类

核心是 Foo\Webservice\WebserviceFoo 类。它提供了请求/类的映射。

protected $_requestHandlersClassMap = array(
  'foo/#main' => "RequestHandler\\RequestHandlerFooDefault",
  'foo/bar'   => "RequestHandler\\RequestHandlerFooDefault",
  'foo/foo'   => "RequestHandler\\RequestHandlerFooDefault",
  'foo/boo'   => "RequestHandler\\RequestHandlerFooDefault",
  'foo/far'   => "RequestHandler\\RequestHandlerFooDefault",
);

请求类

你必须实现至少 execute() 方法，该方法必须返回 TRUE 表示成功。你主要会做你的工作，并设置状态和要返回的数据。

setStatus()：定义状态（默认 200/成功）
setResponseData()：指定要返回的数据
canAccess()：你可以告诉 RLW 此请求是否可以执行
isValid()：你可以告诉 RLW 请求是否正确
alterRequests()：你可以更改所有（子）请求...

数据验证

你可以描述输入数据，RLW 会负责数据验证。

protected $_requestParameterDefinitions = array(
  'freeStringsArray' => array(
     'type' => 'array',
     'nested' => 'string',),
  'sizeStringsArray' => array(
      'type' => 'array',
      'min' => 3,
      'max' => 10,
      'nested' => 'string',),
  );

类型定义

你可以定义自定义用户类型。

protected $_typeDefinitions = array(
  'my_struct' => array(
    'type' => 'struct',
    'struct' => array(
      'foo' => array('type' => 'string'),
      ),
  ),
);

并使用它。

 protected $_requestParameterDefinitions = array(
  'field' => array(
     'type' => '<my_struct>',
     'mandatory' => true,),
 );

PHP SDK

RLW 附带了一个基本的 PHP SDK。

基本请求

require_once "rlw/sdk/php/src/RLW.php";
$ws = new RLW('http://mysite.com/my/api');
$request = $ws->createRequest('foo');
$request->r = rand();
$res = $request->execute();
...

带有子请求

require_once "rlw/sdk/php/src/RLW.php";
$ws = new RLW('http://mysite.com/my/api');
$request = $ws->createRequest('foo');
$request->r = rand();
$bar = $request->subRequest('bar');
$bar->x = 'something';
$res = $request->execute();
...

有关更多示例，请参阅 rlw/sdk/php/tests/FooTest.php。

语法

以下是原始 HTTP 语法。

请求

请求可以是 GET 参数（对于简单请求）或 POST JSON。

例如

GET 请求：/api/foo/?bar=1

等同于

POST 请求：/api/foo/

发送

{
  #request: {bar: 1}
}

如果 API 调用同时具有 GET 和 POST/JSON，API 会合并请求，但 POST 会覆盖 GET。

子请求

POST API 调用可以有“子”请求

{
  #request: {bar: 1},
  mySubRequestTag: {
    #name: 'mySubRequest',
    ...
  }
}

你可以省略 #name

{
  #request: {bar: 1},
  mySubRequest: {...}
}

等同于

{
  #request: {bar: 1},
  mySubRequest: {
    #name: 'mySubRequest',
    ...
  }
}

子请求的响应将像这样发送

{
  #status: <responseStatus>,
  #data: <responseData>,
  mySubRequestTag: <response>,
}

子请求的状态与请求不相关。

响应

响应为 JSON 格式。

{
  #status: {
    code: <int>,
    message: <string>,
    [details: [<string] ]
  },
  #data: <responseData>
}

请求依赖

（子）请求可以定义一个 #requires 键来指定“（子）请求成功依赖”。如果指定的任一（子）请求未成功，则当前（子）请求不会执行。

#requires < string | array<string> > [optional] : [list of] sub request tag to be successful

你可以使用 #main 标签引用主请求。你可以在主请求中放置 #requires。API 将执行拓扑排序以确定正确的执行顺序。

示例

{
  #request: {bar: 1},
  #requires : "myOtherSubRequest",
  myFirstSubRequest: {...}    
  myOtherSubRequest: {"#requires": "myFirstSubRequest", ...},
}

异常

如果出现错误，API 可以引发异常。异常替换了正常响应。

示例

{
  "#exception": {
    type: "Exception",
    code: 0,
    message: "Something is wrong"
  }
}

文件夹

foo：示例用的虚拟 Web 服务
sdk：PHP 基本SDK

quazardous / rlw

维护者

详细信息