2017 © Pedro Peláez
 

library rlw

image

quazardous/rlw

  • Thursday, October 22, 2015
  • by quazardous
  • Repository
  • 1 Watchers
  • 1 Stars
  • 415 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 2 Forks
  • 0 Open issues
  • 1 Versions
  • 0 % Grown

The README.md

RLW

Rest Like Webservice bootstrap, (*1)

Goal

Provide a lightweight bootstrap/framework for REST like webservice/JSON API., (*2)

REST like philosophy

Say you want to handle blog Posts., (*3)

You'll have to provide a getPost() request and a putPost() request. And maybe you'll have a addComment() request. But at the end those three requests will probably return the Post object..., (*4)

With RLW you can define a main post() request and add subrequests : put() and addComment()., (*5)

RLW manages (sub)requests dependencies. So if a Post does not exist subrequests will be cancelled., (*6)

One of the side effects is to save some HTTP calls : you can "package" many actions in one request., (*7)

Bootsrap

The ./foo folder shows a basic webservice (used with PHPUnit tests)., (*8)

Webservice class

The core is the Foo\Webservice\WebserviceFoo class. It provides the (sub)request/class map., (*9)

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

Request class

You must implement at least the execute() method wich must return TRUE if successfull. Mainly you will do your stuff an set status and data to return., (*10)

  • setStatus(): define the ststus (default 200/success)
  • setResponseData(): specify some data to return
  • canAccess(): you can tell RLW if this request can be executed
  • isValid(): you can tell RLW if request is correct
  • alterRequests(): you can alter all (sub)requests...

Data Validation

You can describe the input data and RLW takes care of the data validation., (*11)

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

Type definition

You can define a custom user type., (*12)

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

And use it., (*13)

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

PHP SDK

RLW comes with a basic PHP SDK., (*14)

Basic request:, (*15)

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();
...

With a subrequest:, (*16)

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();
...

see rlw/sdk/php/tests/FooTest.php for more examples., (*17)

Syntax

Here is the raw HTTP syntax., (*18)

Request

Request can be GET params (for simple one) or POST JSON., (*19)

In example:, (*20)

GET request: /api/foo/?bar=1, (*21)

is equivalent to, (*22)

POST request: /api/foo/, (*23)

sending:, (*24)

{
  #request: {bar: 1}
}

If API call has both GET and POST/JSON, API will merge request but POST will take over GET., (*25)

Subrequest

POST API calls can have “sub” requests:, (*26)

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

You can ommit the #name:, (*27)

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

Equivalent to:, (*28)

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

response to sub requests are sent like:, (*29)

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

status for sub request and request are not linked., (*30)

Response

Response is in JSON., (*31)

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

Requests dependency

(Sub) request can define a #requires key to specify ”(sub) request success dependency”. If one of the specified (sub) request is not successful, the current (sub) request is not executed., (*32)

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

You can refer to the main request with a '#main' tag. You ca put the #requires in the main request. The API will perform a topoligical sort to determine the right order of execution., (*33)

Example:, (*34)

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

Exceptions

API can raise an exception if something goes wrong. The exception replaces the normal response., (*35)

Example:, (*36)

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

Folders

  • foo: dummy webservice for example
  • sdk: PHP basic SDK

The Versions

22/10 2015

dev-master

9999999-dev

  Sources   Download

The Requires