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

New in version 10.2

Since version 4.1, requests can be made with basic or basic authentication. Previously, basic authentication was only available when retrieving a bearer token through the authenticate endpoint.

Security and performance considerations

basic authentication is not as secure and less performant than bearer authentication. Because it requires you to encode and transmit your backend username and password with every request, it offers inferior security.

bearer authentication is a token-based system where you first retrieve a temporary token and then use only this token for subsequent requests.

Scheme: `basic`

Generating your authentication string

The basic HTTP authentication schema, uses a Base64-encoded string consisting of a 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=".

You can base64-encode a string by using built-in terminal commands:

# Will output: dGVzdHVzZXI6dGVzdDEyMzQ=
echo -n "testuser:test1234" | base64

Warning

Using online tools for encoding your password is not advisable!

Using `basic` authentication in a request

Authentication is done using the Authorization HTTP header.

curl -XPOST \
     -H 'Authorization: basic dGVzdHVzZXI6dGVzdDEyMzQ=' \
     -v 'https://example.org/rest/pages/testPage' \
     -d '{"data":{"title":"Test Name","pid":"siteRootPage"}}'

The request will return a JSON response body:

{"success":true, ...}

Fixing Apache and the authorization HTTP header

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)

Retrieving an authentication token

When you use the bearer HTTP authentication scheme, you must first retrieve an authentication token through the authenticate endpoint using `basic` authentication.

curl -XPOST \
     -H 'Authorization: basic dGVzdHVzZXI6dGVzdDEyMzQ=' \
     -v 'https://example.org/rest/authenticate'

Note

authenticate is a special endpoint used when retrieving a token. For obvious reasons, it only supports basic authentication.

This request will return a JSON response body including a token that can be used on subsequent requests:

{"success":true,"token":"f3c0946fb05aae4ad50897e9060ab4e8"}

Authenticating a request with a bearer token

You supply the bearer token using the Authorization HTTP header in your request:

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

HTTP Methods

POST

Create a record.

PUT

Update a record.

PATCH

Update a record if it exists, otherwise create it.

DELETE

Delete a record.

curl -XDELETE \
     -H 'Authorization: bearer f3c0946fb05aae4ad50897e9060ab4e8' \
     -v 'https://example.org/rest/pages/testPage'

Optional HTTP Headers

Interest-Disable-Reference-Index

Required: false
Type: Boolean

Disable updating the reference index during the request. This has a positive performance impact. You can (and should) reindex the reference index manually afterwards.