Tutorials: Developing REST-ful Web Services

Some sites are by inception created only to serve other sites via HTTP requests. REST is a de-facto standard in developing such sites (aka web applications) by defining a number of architectural constraints, among whom the most important are:

Wny site that follows above principles is called RESTful and functions as a web service container. Lucinda allows you to create a RESTful web service container by a combination of XML and PHP requirements.

XML Requirements

Virtually all modern RESTful web service containers use application/json format in responses, by virtue of its brevity and ease of encoding/decoding. So the first step is to make your application serve only json:

If authentication & authorization is required, make sure <persistence> tag @ stdout.xml is either empty or using synchronizer tokens (recommended) or json web tokens. To use recommended setting:

<security ...> ... <persistence> <synchronizer_token secret="LEt7_Lz}30g*zXD"/> </persistence> ... </security>

Assuming you have defined a secret unique to your application, this generates a secure token to be served back to caller after successful authentication. Any authentication/authorization calls will be answered using this format:

{"status":STATUS, "body":{"status":AUTH_STATUS, "callback":CALLBACK, "token":TOKEN}}


Any other calls will be answered with this format:

{"status":STATUS, "body":{"token":TOKEN, ...}}


PHP Requirements

Once a TOKEN is received, it must be presented by CLIENT as Authorization bearer header in order for SERVER to authenticate access to protected resources. Example request:

$ch = curl_init(); curl_setopt($ch, CURLOPT_URL,"PROTOCOL://RESTFUL_SITE/PROTECTED_RESOURCE"); curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Authorization: Bearer ".$token, ... )); ...

To prevent replay and criminal usage, TOKEN is both IP and TIME bound:

  1. if someone tries to use same token from a different IP, an HTTP 400 response is received.
  2. if someone tries to use a token after more than an hour idle, token is refused
  3. on every valid usage, token is renewed (if it is more than 10 minutes old) and always returned

In order to be REST compliant, developers must not record state and use the new generated value on subsequent requests!

Each resource in a REST-ful web service container must be identifiable via a tag without view whose controller attribute points to a RestController instance whose method names map HTTP methods supported:

HTTP method OPTIONS support is already done by framework, while HEAD/CONNECT/TRACE are seldom used (but supported same as above). To envision an example of a RestController supporting GET/POST:

class MyController extends { // executed automatically when route is called using GET public function GET(): void { $myModel = new MyModel(); $this->response->view()["info"] = $myModel->getInfo(); } // executed automatically when route is called using PUT public function PUT(): void { $myModel = new MyModel(); $myModel->save($this->request->parameters("data")); } }