REST.md 4.26 KB
Newer Older
Carsten  Rose's avatar
Carsten Rose committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
====
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:

15
    typo3conf/ext/qfq/Classes/Api/rest.php
Carsten  Rose's avatar
Carsten Rose committed
16
17
18

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

19
    http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/1/restAddress/123?myEmail=jonni@miller.com
Carsten  Rose's avatar
Carsten Rose committed
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

    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:

42
   curl -X GET "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson" 
Carsten  Rose's avatar
Carsten Rose committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

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:

58
   curl -X POST "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson" -d '{"name":"Miller","firstname":"Jonni"}'
Carsten  Rose's avatar
Carsten Rose committed
59
60
61
62
63
64
65
66
67
68
69
70
71

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:

72
   curl -X PUT "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/1" -d '{"name":"Miller","firstname":"Jonni"}'
Carsten  Rose's avatar
Carsten Rose committed
73
74
75
76
77
78
79
80
81
82
83
84
85

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:

86
   curl -X DELETE "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/1" 
Carsten  Rose's avatar
Carsten Rose committed
87
88
89
90
91
92
93
94
95
96
97
98
99

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:

100
    curl -X GET -H 'Authorization: Token token="mySuperSecretToken"' "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson/"
Carsten  Rose's avatar
Carsten Rose committed
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

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: 

123
    curl -X POST "http://localhost/qfq/typo3conf/ext/qfq/Classes/Api/rest.php/restPerson?XDEBUG_SESSION_START=1" -d '{"name":"Miller","firstname":"Jonni"}'
Carsten  Rose's avatar
Carsten Rose committed
124
125

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