REST API¶
Basic request URL¶
Requests to the REST API usually follows a simple pattern, where all of the parts, except from the endpoint, are optional or can be supplied elsewhere:
http://www.example.org/[endpoint]/[table]/[remoteId]/[language]/[workspace]
Example with values added:
http://www.example.org/rest/tt_content/Content-531/nb-NO/0
Optional URL parts¶
[language]
and [workspace]
are fully optional and can be left out entirely:
http://www.example.org/[endpoint]/[table]/[remoteId]
They can also be supplied in the query string:
http://www.example.org/[endpoint]/[table]/[remoteId]?language=[language]&workspace=[workspace]
Authentication¶
Scheme: basic¶
Initial authentication is done using the basic
HTTP authentication schema,
where a Base64-encoded string is submitted to the server. The string is a TYPO3
backend username and the corresponding password, separated by a colon: :
.
Given the username "testuser" and password "test1234", the concatenated string will be "testuser:test1234" and the Base64-encoded version: "dGVzdHVzZXI6dGVzdDEyMzQ=".
curl -XPOST \
-H 'Authorization: basic dGVzdHVzZXI6dGVzdDEyMzQ=' \
-v 'https://example.org/rest/authenticate'
This request will return a JSON response body including a token that can be used on subsequent requests:
{"success":true,"token":"f3c0946fb05aae4ad50897e9060ab4e8"}
When using Apache there is a need to add the following to .htaccess
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
Scheme: bearer (OAuth)¶
For any other request, you must use bearer
HTTP authentication scheme,
supplying an authentication token, such as the one supplied by the basic
authentication request mentioned above:
curl -XPOST \
-H 'Authorization: bearer f3c0946fb05aae4ad50897e9060ab4e8' \
-v 'https://example.org/rest/pages/testPage' \
-d '{"data":{"title":"Test Name","pid":"siteRootPage"}}'
Batch requests¶
[table]
and [remoteId]
must be supplied, but can be a part of the [data]
array. This makes it possible to supply batch data affecting multiple records
and tables.
Given a request with only [table]
supplied in the URL:
http://www.example.org/[endpoint]/[table]
Multiple records in the same table¶
You can insert or update multiple records within [table]
. Your data array
could look something like this:
{
"Record-1": {
"title": "My first record",
"page": ["Page-916"]
},
"Record-2": {
"title": "My second record",
"page": ["Page-376"]
}
}
Multiple records in multiple tables¶
You can also leave out the table and insert or update multiple records within multiple tables:
"pages": {
"Page-1": {
"title": "My first page"
},
"Page-2": {
"title": "My second page"
}
},
"tt_content": {
"Content-1": {
"heading": "Welcome to the first page",
"pid": "Page-1"
},
"Content-2": {
"heading": "Welcome to the second page",
"pid": "Page-2"
}
}
Multilingual records¶
It is even possible to insert records in multiple languages by adding a language layer to the data:
"pages": {
"Page-1": {
"en": {
"title": "My first page"
},
"nb": {
"title": "Min første side"
}
},
"Page-2": {
"en": {
"title": "My second page"
}
},
},
"tt_content": {
"Content-1": {
"en": {
"heading": "Welcome to the first page",
"pid": "Page-1"
},
"nb" {
"heading": "Velkommen til den første siden",
"pid": "Page-1"
}
},
}