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:

each resource to serve is identified by an URI
operations clients can do to a resource are identified by HTTP method its URI was called with
resource served is atomic (depending on no other), thus no state (eg: session) should be stored
response must be complete, requiring no further requests to be collapsed
responses must be cacheable and servers interchangeable, to enforce load balancing

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:

modify default_format attribute of <application> @ stdout.xml and <application> @ stderr.xml tag to equal "json":
<application default_format="json" ...> ... </application>
make sure only <resolver> for json is left in stdout.xml and stderr.xml:
<resolvers> <resolver format="json" content_type="application/json" class="Lucinda\Project\ViewResolvers\Json" charset="UTF-8"/> </formats>

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}}

Where:

STATUS: whether or not it was an error. Value can be:
- ok: if everything was ok, described by AUTH_STATUS below.
- error: if something failed, described by AUTH_STATUS below.
AUTH_STATUS: authentication/authorization result status. Value can be:
- login_ok: login was successful.
- login_failed: login failed (wrong username/password).
- logout_ok: logout was successful
- logout_failed: logout failed (user not logged in)
- redirect: redirection is required to oauth2 provider to get authorization code
- unauthorized: user tried to access a resource requiring authentication while not authenticated
- forbidden: authenticated user is not allowed access to that resource
- not_found: requested resource could not be related to an authorization schema
CALLBACK: URI to redirect to as a result of authentication/authorization
TOKEN: value of synchronizer token for clients to use in subsequent requests

Any other calls will be answered with this format:

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

Where:

STATUS: whether or not it resulted into an error. Value can be:
- ok: if everything was ok
- error: if an error has occurred
TOKEN: regenerated synchronizer token for clients to use in subsequent requests

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:

if someone tries to use same token from a different IP, an HTTP 400 response is received.
if someone tries to use a token after more than an hour idle, token is refused
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 <route> tag without view whose controller attribute points to a Lucinda\Framework\RestController instance whose method names map HTTP methods supported:

GET: called automatically when a HTTP GET request is received on that resource URI.
Must return complete resource details!
POST: called automatically when a HTTP POST request is received on that resource URI.
Must be used when creating a resource and server must respond with a status header only!
PUT: called automatically when a HTTP PUT request is received on that resource URI.
Must be used when updating a resource and server must respond with a status header only!
DELETE: called automatically when a HTTP DELETE request is received on that resource URI.
Must be used when deleting a resource and server must respond with a status header only!

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 Lucinda\Framework\RestController supporting GET/POST:

namespace Lucinda\Project\Controllers

use Lucinda\Project\Foo\Bar;

class MyController extends \Lucinda\Framework\RestController
{
    // executed automatically when route is called using GET
    public function GET(): void
    {
        $myModel = new Bar();
        $this->response->view()["info"] = $myModel->getInfo();
    }

    // executed automatically when route is called using PUT
    public function PUT(): void
    {
        $myModel = new Bar();
        $myModel->save($this->request->parameters("data"));
    }
}

□ ×