The REST API for integrators #

This page is for developers of systems that call Exponential over HTTP. The REST content API is served by the ezprestapi extension (required as ~1.2.6 by the root composer.json) on the kernel's REST framework (kernel/private/rest/). The complete reference is REST API v1 and v2; this page picks out what an integration needs and adds the client-side advice.

Contents #

1. What it can and cannot do
2. The routes
3. Reading a large list page by page
4. Creating and removing
5. Answers your client must handle
6. A small client in Python
7. Settings that change the behavior

What it can and cannot do #

Reads answer at v1 and v2, writes at v2 only. Links inside a v1 answer stay in v1.

The routes #

All paths are below /api/ezp/v1 or /api/ezp/v2 (the prefix ezpl is an alias of ezp).

Query parameters of the reads: ResponseGroups=Metadata,Locations,Fields chooses the parts of the answer, and OutputFormat=xhtml adds the rendered view in renderedOutput.

Reading a large list page by page #

Ask for the count first, then walk the list with a fixed page size. Sort by a stable key so that pages do not shift while you read.

export EXP_API_KEY='expk_...'
BASE=https://example.com/api/ezp/v1

curl -s -H "Authorization: Bearer $EXP_API_KEY" "$BASE/content/node/<node id>/childrenCount"
curl -s -H "Authorization: Bearer $EXP_API_KEY" \
     "$BASE/content/node/<node id>/list/offset/0/limit/50?ResponseGroups=Metadata,Fields"
curl -s -H "Authorization: Bearer $EXP_API_KEY" \
     "$BASE/content/node/<node id>/list/offset/50/limit/50?ResponseGroups=Metadata,Fields"

Only the children of one node are listed. To read a deep tree, walk it level by level, or let a server-side export write the whole subtree in one run (Writing an export).

Creating and removing #

# create and publish a folder below a parent (v2 only)
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/create \
     -d parentNodeID=<parent node id> -d classIdentifier=folder -d languageLocale=eng-US -d name='From the ERP'
# {"message":"Created","objectId":<object id>,"nodeId":<node id>}

# remove it with all its locations and everything below them (v2 only)
curl -s -X DELETE -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/delete/<node id>

The create fields are parentNodeID, classIdentifier, languageLocale, then the attribute identifiers of the class. The create is checked as content/create of that class below that parent in that language, and the publish workflow runs as it does in the administration. The create backend is nxc_powercontent.

Answers your client must handle #

A small client in Python #

Only the standard library:

import json, os, time, urllib.error, urllib.request

BASE = 'https://example.com/api/ezp/v1'
KEY = os.environ['EXP_API_KEY']

def get(path):
    for attempt in range(5):
        request = urllib.request.Request(BASE + path, headers={'Authorization': 'Bearer ' + KEY})
        try:
            with urllib.request.urlopen(request, timeout=30) as answer:
                return json.load(answer)
        except urllib.error.HTTPError as error:
            if error.code in (429, 502, 503):
                time.sleep(int(error.headers.get('Retry-After', 2 ** attempt)))
                continue
            raise
    raise RuntimeError('gave up on ' + path)

print(get('/content/node/2')['metadata']['objectName'])

Settings that change the behavior #

settings/rest.ini, overridden in settings/override/rest.ini.append.php:

After a change, clear the INI cache (php bin/php/ezcache.php --clear-tag=ini --allow-root-user), reload PHP-FPM and restart Velocity if it serves the site.

Related pages #

• REST API v1 and v2 and Personal API keys
• ezprestapi, nxc_powercontent
• The REST API for app creators
• Choosing credentials for an integration
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.