====
REST
====

* https://en.wikipedia.org/wiki/Representational_state_transfer
* https://restfulapi.net
* https://poe-php.de/tutorial/rest-einfuehrung-in-die-api-erstellung
* https://blog.restcase.com/top-5-rest-api-security-guidelines/

General Concept
===============

* There is one PHP file to handle all REST calls:

    typo3conf/ext/qfq/Classes/Api/rest.php

* All further endpoints are appended after rest.php, seperated by '/'. Example:

    http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/1/restAddress/123?myEmail=jonni@miller.com

    The argument 'myEmail' is just to show how  GET variables will be submitted.
    
* Each `level` is a QFQ form. In the above example: `restPerson` and `restAddress`     
* A QFQ form will be enabled for REST calls via field 'Permit REST'. Possible options: get, insert (post), update (put), delete
* An optional HTML header token based 'authorization' is supported.
* At least one `level` (= form name) has to be given. 
* Multiple `level/id` tuple are possible.
* Only the last level will be used. The last `level` becomes automatically `form` in STORE_TYPO3.
* The last `id` becomes automatically `r` in STORE_TYPO3.
* Previous `level` and `id` are accessible via `{{_id1:C}}`, `{{_form1:C:alnumx}}`,`{{_id2:C}}`, `{{_form2:C:alnumx}}`, ...
* Import/Export data has to be/is JSON encoded.
* The following settings has no impact to QFQ forms called via REST: `form.Permit New`, `form.Permit Edit`  

HTML Requests
=============

GET - export
------------
 
Example:

   curl -X GET "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson" 

Details:

* no `id` or `id=0` (example: 1, 123): The result of `Form.parameter.restSqlList` will be generated.
* `id>0` (example: 1, 123): the result of `Form.parameter.restSqlData` will be generated.
* The whole resultset will be JSON encoded.
* It's not possible to render subrecords. This has to be done via a sub level (next form). 
* Future: If this is not sufficient, a possible solution might be a `report`-notation (special FormElement), which do 
  not implode all output, but leave the rows/cells intact as an array - the json_encode will then to the rest. 

POST - insert
-------------

Example:

   curl -X POST "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson" -d '{"name":"Miller","firstname":"Jonni"}'

Details:

* The data has to be JSON encoded transferred to the REST API. 
* The JSON stream will be decoded to an array and copied to $_POST.
* The further process is identically to a standard 'form submit'.
* There should be no `id` given or `id=0`.

PUT - update
------------

Example:

   curl -X PUT "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/1" -d '{"name":"Miller","firstname":"Jonni"}'

Details:

* The data has to be JSON encoded transferred to the REST API. 
* The JSON stream will be decoded to an array and copied to $_POST.
* The further process is identically to a standard 'form submit'.
* There have to be an `id>0`.

Delete
------

Example:

   curl -X DELETE "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/1" 

Details:

* The data has to be JSON encoded transferred to the REST API. 
* The JSON stream will be decoded to an array and copied to $_POST.
* The further process is identically to a standard 'form submit'.
* There have to be an `id>0`.

Header Token Authorization 
==========================

Example:

    curl -X GET -H 'Authorization: Token token="mySuperSecretToken"' "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/"

Static token
------------
    
Per form configure `form.parameter.restToken=mySuperSecretToken`.

Dynamic token
-------------

The client supplied authorization token is available via the client store: `{{Authorization:C:alnumx}}`.

Take the Client token and check if it saved in a table with all user token:   
 
    form.parameter.restToken={{SELECT a.token FROM Auth AS a WHERE a.token='{{Authorization:C:alnumx}}' }}

DEBUG
=====

Append the GET variable `?XDEBUG_SESSION_START=1`

Example: 

    curl -X POST "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson?XDEBUG_SESSION_START=1" -d '{"name":"Miller","firstname":"Jonni"}'

PhpStorm with activated debugger will stop at any breakpoint and 'stepping' through the code is possible.