Commit 5091176a authored by Carsten  Rose's avatar Carsten Rose
Browse files

REST.md: add

parent 2e7b662e
Pipeline #1560 passed with stage
in 2 minutes and 22 seconds
====
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/Source/api/rest.php
* All further endpoints are appended after rest.php, seperated by '/'. Example:
http://localhost/qfq/typo3conf/ext/qfq/Source/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/Source/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/Source/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/Source/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/Source/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/Source/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/Source/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.
......@@ -7511,7 +7511,7 @@ list
A list of records will be exported. Defined via 'form.parameter.restSqlList'. This mode is selected if there is no
id or id=0.
.. note:
.. note::
There are *no* native-FormElements necessary or loaded. Action FormElements will be processed.
......@@ -7551,12 +7551,17 @@ Form.parameter:
| restToken | Optional. User defined string or dynamic token (see `restAuthorization`_). |
+-------------------+----------------------------------------------------------------------------------+
.. note:
.. note::
There are no `special-column-names`_ available in `restSqlData` or `restSqlList`. Also there are no
SIPs possible, cause REST typically does not offer sessions/cookies (which are necessary for SIPs).
.. important::
If there is an ``ìd`` given, a record in the named primary with the specified table has to exist.
If not, an error is thrown.
POST - Insert
-------------
......@@ -7649,7 +7654,7 @@ Form.parameter:
| restToken | Optional. User defined string or dynamic token (see `restAuthorization`_). |
+-------------------+----------------------------------------------------------------------------------+
.. note:
.. note::
There are *no* native-FormElements necessary - but might exist for dependent records to delete. Action FormElements
will be processed.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment