Backend services over ezjscore (expservices) #

Read this page if you build a remote admin app (GTK, Qt, KDE/GNOME, iOS, Android, shell) or a JavaScript frontend on top of Exponential. extension/expservices turns the ezjscore server functions into a library of remote services that offer the features of Exponential, with discovery, one answer envelope, policies per service and personal API tokens. Version 0.1.0 (first draft, 2026-10-02).

In short #

Host names in the examples are placeholders (https://www.example.com); use your own. The shipped shell client takes the address from -u or EXPSERVICES_URL; always set one of them.

Overview #

What an ezjscore server function is #

ezjscore (extension/ezjscore) lets a page call PHP over HTTP. A server function is a public static method of a class that is registered in ezjscore.ini as a block [ezjscServer_<name>] (Class=<class>). It is called as

<root>/ezjscore/call/<name>::<function>[::<arg>[::<arg>...]]

(the admin siteaccess has the same URL below /admin/). The router (ezjscServerRouter) refuses any class that has no block in ezjscore.ini, calls <class>::<function>( array $args ) and answers in the format of the Accept header or ?ContentType=json|xml|text. ezjscore/call itself does not check a policy: every function checks for itself. Several calls can be sent in one request: POST ezjscServer_function_arguments with the calls joined by @SEPARATOR$.

The ezjscore answer wraps the return value: {"error_text": "", "content": <what the function returned>}. expservices functions return the envelope below as content.

The classes: one domain, one class, one block #

Every domain is a class exp<Domain>Services extending expServiceBase, registered in extension/expservices/settings/ezjscore.ini.append.php as [ezjscServer_exp<domain>], so a service of the domain system is called ezjscore/call/expsystem::version. Each public static method is a service and is declared in the class's public static $services:

'version' => array( 'summary' => '...', 'access' => 'public' | 'user' | array( 'setup', 'system_info' ),
                    'write' => false, 'args' => array( 'node_id' => 'int' ), 'returns' => '...' )

ezjscServerRouter::call() hands every class that extends expServiceBase to expServiceBase::invoke(), which checks that the service is declared, calls it, and turns every exception into the error envelope.

Declare the list as the property's value in the class body, never by an assignment after the class (expFooServices::$services = ...;). A persistent Velocity worker puts the statics of a class it first loaded during a request back to their declared value before its next request, and include_once does not run such an assignment again: from the second request on, every service of the class answered "not declared" (404) on that worker, and the extension point survey listed them as missing. The ten users and access domains did this until 2026-10-12 (207 services; expUsersDeclarationsTest::testTheServicesSurviveAResetToTheDeclaredValue guards it now).

Discovery #

The domain is the part after exp of the block name (session, system, ini, cache, ...). The calls to the discovery functions are public; every other service checks its own access.

The envelope #

{ "ok": true,  "data": <the result>, "meta": { ... } }
{ "ok": false, "error": { "code": 403, "message": "No access to setup/managecache" } }

Lists are paged: data is the items and meta is total, offset, limit, count, has_more.

Authentication #

Sign in once with expsession::login (POST username, password); the response sets the session cookie, which a non-browser client keeps in a cookie jar and sends with every call. expsession::whoami says who the session is, expsession::token returns the form token needed for writes, expsession::ping keeps the session alive, expsession::logout ends it. Clients that cannot keep a cookie use a personal API token instead, see below.

curl -c jar -d 'username=admin' --data-urlencode 'password=...' https://site/ezjscore/call/expsession::login
curl -b jar https://site/ezjscore/call/expsession::whoami

Authentication with an API token #

For apps, scripts and servers a session cookie is the wrong tool: it expires, it needs the sign-in flow and a form token for every write. A personal API token is the alternative. A signed-in user (session login, not a token) creates one with expsession::tokenCreate (POST name, expires_in_days 1 to 365, default 90); the answer carries the token once (data.token, expt_ and 48 hex characters). Only its SHA-256 hash is stored (table expservices_token), so a lost token cannot be read back, only revoked (expsession::tokenRevoke, POST id) and replaced. expsession::tokenList lists the caller's own tokens: id, name, a hint (the first characters), created, last used, expiry, revoked, valid, never the token.

curl -b jar -H 'X-CSRF-Token: <form token>' --data-urlencode 'name=backup script' https://site/ezjscore/call/expsession::tokenCreate?ContentType=json
curl -H 'Authorization: Bearer expt_...' https://site/ezjscore/call/expsession::whoami?ContentType=json
curl -H 'X-Exp-Token: expt_...' --data-urlencode 'id=7' https://site/ezjscore/call/expsession::tokenRevoke?ContentType=json

• Sending it. Authorization: Bearer <token>, or the header X-Exp-Token: <token>. Use X-Exp-Token where a proxy or FastCGI setup does not hand the Authorization header to PHP (Apache with mod_proxy_fcgi needs CGIPassAuth On or SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1; on the reference installation Authorization does not arrive and X-Exp-Token is the header that works). The shipped clients send both.
• What it does. Before any guard looks at the user, the base signs the request in as the token's user, for this one request only: the session is not touched, so no cookie is created and nothing stays signed in afterwards. Every other guard is unchanged: the same policies and limitations as for that user, POST for writes, the audit event of every write.
• Writes need no form token with a bearer token (but still POST). The form token protects a browser, which attaches its cookie to a request a hostile page makes on its own; a request that carries the token in a header it must set itself cannot be forged that way, so there is nothing for the form token to prove. A request without the token header falls back to the cookie and the form token as before.
• Refusals. An unknown, revoked or expired token, or a token whose user is disabled, answers 401 on every service, public ones too (a client must notice that its token died, not silently become anonymous). A token cannot create tokens (403): that needs the session login. Tokens of other users are invisible (404).
• Audit. access.expservices.token.create, access.expservices.token.revoke and access.expservices.token.failed (a refused token, with the reason) in the access channel; the taxonomy branch expServicesAuditBranch is registered in extension/expservices/settings/audit.ini.append.php. Uses are not logged one by one; the token's last_used is updated at most once a minute.
• Install. The table is in extension/expservices/sql/{mysql,postgresql,sqlite}/schema.sql (the extension has no share/db_schema.dba); create it on an existing installation by running the schema of your database engine once, for example mysql -u YOUR_USER -p YOUR_DATABASE < extension/expservices/sql/mysql/schema.sql (it is a plain CREATE TABLE: skip it when the table exists).
• Only a token's hint is ever shown again; keep the token in the platform's secret store (Keychain, Keystore, KWallet, libsecret), never in source code or a URL.

Access #

'access' of a service is public (anybody), user (any signed-in user) or array( module, function ), a policy of the user (eZUser::hasAccessTo; a limited policy passes the check, and the service then checks the object, e.g. canRead() of a node). A missing login answers 401, a missing policy 403.

A classic server function (an [ezjscServer_<name>] block of ezjscore.ini) is guarded by its Functions[], checked against the ezjscore/call policy with the FunctionList limitation. RequirePolicy sets how: not set, Functions[] is checked and a refused call is answered with its error text in a 200 answer, as before; disabled, it is not checked; enabled, it is checked and a request whose calls are all refused is answered with 403. ezjscnode ships with Functions[]=ezjscnode and RequirePolicy=disabled; new installations write enabled (see Roles and policies, section 8). ezjscServerRouter::getInstance() reports why it returned null in an optional fourth argument (invalid, access, policy-required). The idea of guarding ezjscnode by a policy comes from Mugo Web's LoveStack distribution (commit aa307a7ff3), with thanks.

Paging #

Services that list take limit and offset arguments (expsystem::phpextensions::10::20 is 10 items from 20). The default and the maximum are in expservices.ini [Paging] (25 and 200).

Errors #

Writes #

A service with 'write' => true needs a POST, the form token (field ezxform_token or header X-CSRF-Token; get it from expsession::token), and its policy; arguments come in the POST body (expServiceBase::post()), not in the URL. Every successful write records the audit event service.<domain>.<method> (expAudit), besides the events the kernel operation writes itself. expservices.ini [Writes] can switch the token check (tests only) and the audit off. A request signed in by an API token needs POST but no form token (see "Authentication with an API token").

Writing a service #

class expFooServices extends expServiceBase
{
    public static $services = array( 'bar' => array( 'summary' => '...', 'access' => array( 'content', 'read' ),
        'write' => false, 'args' => array( 'node_id' => 'int' ), 'returns' => '...' ) );

    public static function bar( $args )
    {
        self::guard( __FUNCTION__ );
        $node = self::node( self::arg( $args, 0, 'int' ) );
        return self::ok( array( 'name' => $node->attribute( 'name' ) ) );
    }
}

Helpers: arg(), post(), paging()/pageOf(), ok(), page(), guard(), audit(), node(), can(). Register the class in ezjscore.ini.append.php, run php bin/php/ezpgenerateautoloads.php -e.

One declaration, three channels #

The same declaration serves HTTP (ezjscore/call/exp<domain>::<method>), MCP (the tools exp_svc_<domain>_<method> an MCP server generates from the catalogue) and, when the service opts in, the assistant of the extension expai. A read service opts in with 'ai' => true, or with 'ai' => array( 'summary' => '...' ) to give the model its own description; services are private to the assistant by default, and a service with 'write' => true is never offered. The catalogue reports the flag as ai. The assistant calls the service in process as the logged-in editor, with the service's own access check, the policy ezjscore/call and expai's policy expai/services (limitation Domain); expai's data policy filters the answer. Opted in here: expnode::childrenNames, childrenCount, breadcrumb, tree, latest, find; expsection::list, ofNode; expstate::groups, ofObject; exptags::roots, children, tree, search, ofnode. A site can opt in more without code changes in expai.ini [ServiceTools] (see the documentation of expai, doc/service-tools.md).

Testing a call #

extension/expservices/bin/expservices-client.sh -u https://www.example.com call expsystem::version   # from a shell
php vendor/bin/phpunit tests/tests/extension/expservices/

Domains #

Catalogue (expservices, 5 services) #

Discovery of the API; every call is public.

Session and authentication (expsession, 11 services) #

Remote clients sign in once and keep the session cookie, or use a personal API token; see the Authentication sections.

System information (expsystem, 16 services) #

What the installation is and runs on; the secrets of the installation are never part of an answer.

Settings (read-only) (expini, 10 services) #

Reads the INI settings as the siteaccess of the request sees them. Values of secrets (password, token, key ...) are masked exactly as exp:ini masks them.

Caches (expcache, 14 services) #

The clear services are writes: POST, the form token, setup/managecache, an audit event. Pass dry_run=1 to see what would be cleared.

Cronjobs (expcronjob, 7 services) #

Extensions (expextension, 9 services) #

Packages (exppackage, 7 services) #

Workflows and triggers (expworkflow, 10 services) #

Velocity (expvelocity, 5 services) #

Paths of the server stay on the server and are not part of the answers.

Extension point survey (rad) (exprad, 7 services) #

Debug summary (expdebug, 6 services) #

Media and other services: 218 services in 14 domains #

Written by the media/other part of expservices: extension/expservices/classes/media/ (images, files, media, tags) and classes/misc/ (layouts, audit, subitems, newsletters, sitemaps, statistics, designs, languages, links, PDF). Domains of extensions answer 404 ... is not available when the extension is inactive. Tests: tests/tests/extension/expservices/media/ and misc/ (live database, test content under the Media root node 43 removed in tearDown, never a test database); the services were also checked over HTTP.

Images and aliases (expimage, 18 services) #

Image aliases (image.ini), original image information and the URL of any alias of a node image. Reads follow content/read on the node; purge needs content/edit.

Files and downloads (expfile, 16 services) #

Binary files: information, the content/download URL (the download itself checks content/read), time limited signed links (HMAC over node, attribute and expiry with the site secret; verify is public) and download statistics.

Audio and video (expmedia, 10 services) #

The ezmedia datatype: player settings, file information, URL, listings and statistics.

Tags (exptags, 27 services) #

The eztags tree with the eztags policies (tags/read, add, edit, delete, addsynonym). Answers 404 "not available" when eztags is inactive. attach and detach change the tags attribute of a node (content/edit on the node).

Layouts (explayout, 27 services) #

explayouts: layouts, zones (a linked zone answers the blocks of its shared layout), blocks, rules, and the layout a node or path resolves to (computed without touching the resolver cache). Policies explayouts/read and explayouts/edit; the writes use the layout service of explayouts_core.

Audit (read only) (expaudit, 19 services) #

Policy audit/read, narrowed to the channels of its Channel limitation; every use is recorded as system.audit.read. Figures need the audit index (409 when it is not usable). Nothing here verifies, exports or changes the audit.

Subitems columns (expsubitems_svc, 12 services) #

The column catalogue and rows of the admin subitems list in the expservices envelope. The block is named expsubitems_svc because expsubitems is the original ezjscore server function of the admin list, which stays as it is. rows takes the columns as an argument (comma list of non built-in column keys).

Newsletters (expnewsletter, 13 services) #

cjw_newsletter: lists, editions, subscriber counts and a user's own subscriptions. subscribe and unsubscribe act on the signed-in user's own account e-mail only; a new subscription starts pending and follows the extension's confirmation rules. 404 "not available" when the extension is inactive.

Sitemaps (expsitemap, 11 services) #

Entries of the content tree as a sitemap lists them (loc, lastmod, changefreq, priority; settings of bcgooglesitemaps.ini), the sitemap index and the generated files.

Statistics (expstats, 16 services) #

Search phrases, content counts, growth, languages, users and sessions. Content figures follow content/read, the rest needs setup/administrate.

Designs and templates (expdesign, 13 services) #

Read only, setup/administrate: designs, bases, the overrides of override.ini, the templates a design resolves, and the source of a template inside a design directory (path checked, 512 KB at most).

Languages and translations (explanguage, 14 services) #

Content languages, language masks, locales, and the progress of the interface translations in share/translations.

External links (expurl, 12 services) #

The links stored by URL attributes: lists, search, validity, the objects using a link. check requests a stored link with HEAD, without redirects, only for http and https addresses that resolve to public hosts (loopback, private, link-local and credentials are refused with 422).

PDF (exppdf, 10 services) #

PDF links of nodes (content/pdf/<node>, which checks the policy again when the link is followed) and the PDF export definitions of the pdf module.

Clients #

Every service is a plain HTTP call, so any language with an HTTP client and a cookie jar is a client. The contract all the examples below follow:

1. Wire format. GET|POST <site>/ezjscore/call/<service>[::arg...]?ContentType=json with Accept: application/json. ezjscore wraps the answer: { "error_text": "", "content": <envelope> }. error_text is set only when the call itself could not be routed; the service's own result (or its error) is content, see "The envelope". Arguments in the URL are percent-encoded and joined with ::; a write sends its arguments as POST form fields.
2. Auth. POST expsession::login with username and password (form encoded). The answer's Set-Cookie is the session; keep it in a cookie jar. The answer also carries the new session's form token (data.token), which replaces any token fetched before the login. Anonymous calls work for the services whose access is public. Or use a personal API token (expsession::tokenCreate, see "Authentication with an API token"): send Authorization: Bearer <token> and X-Exp-Token: <token> with every call, keep no cookie, fetch no form token; writes are still POST.
3. Writes. With an API token a write is only a POST (no cookie, so no form token). With the session: fetch expsession::token (data.token, data.field = ezxform_token, data.header = X-CSRF-Token), then POST with the token as the field ezxform_token and as the header X-CSRF-Token. A missing or wrong token is a 403.
4. Errors. HTTP 200 does not mean success: look at content.ok. content.error.code is 400/401/403/404/409/422/500 (table in "Errors"). A 401 means sign in again, a 403 a missing policy or token (fetch a fresh token once and retry once, never loop), 404/409/422 are for the user to see. A non-200 HTTP status or a body that is not JSON is a transport fault (proxy, TLS, server down): retry with backoff, do not interpret.
5. Paging. List services take offset and limit as their last two URL arguments and answer meta.total, meta.offset, meta.limit, meta.has_more. Loop while has_more is true (or offset + count < total); keep limit at or below expservices.ini [Paging] MaxLimit (200).
6. Discovery. expservices::catalog gives every service with its args, access, write; generate a typed client from it, or call expservices::service::<domain>::<method> for one descriptor.

Toolchains and what was compiled (checked 2026-10-02 on the build machine): only bash+curl, python3 (with requests and PyGObject gi) and g++ without Qt exist. The shell and Python clients and the GTK/Python snippet (both variants) were extracted from this guide and run against the live site. The Kotlin, Swift, Objective-C and Qt/C++ snippets could not be compiled here (no kotlinc, swiftc, clang/gobjc or Qt headers); each of them says so, and they are written against the documented APIs of OkHttp 4, URLSession, NSURLSession and Qt 5/6 Network and reviewed by hand. Compile them in your project before relying on them.

In the examples $SITE is the base URL, e.g. https://www.example.com (or https://www.example.com/<siteaccess> when the installation needs a siteaccess in the path), expnode::children is a paged read and expforum::reply stands for any write service (take a real one from the catalogue). The shell and Python clients are in extension/expservices/bin/ and are tested against the live services; the other snippets follow the same contract and are meant as the starting point of an app.

Shell (bash + curl): extension/expservices/bin/expservices-client.sh (tested here) #

export EXPSERVICES_URL=https://www.example.com
expservices-client.sh whoami                          # anonymous or signed in, pretty printed
expservices-client.sh catalog session                 # the services of one domain
expservices-client.sh call expsystem::version         # any read call; arguments follow, joined with ::
expservices-client.sh login editor                    # asks for the password (or EXPSERVICES_PASSWORD); cookie jar kept
expservices-client.sh page expnode::children 2 --limit 50 --max 500   # every item of a paged service, one JSON per line
expservices-client.sh post expforum::reply topic=123 'message=Hello' # write: token fetched and sent as field and header
expservices-client.sh --raw call expsession::ping     # the answer as received
EXPSERVICES_TOKEN=expt_... expservices-client.sh post expforum::reply topic=123 message=Hi   # API token: no login, no form token

The cookie jar is ${XDG_CACHE_HOME:-~/.cache}/expservices/cookies.txt (--jar or EXPSERVICES_JAR change it). Exit status: 0 ok, 1 service error (error 401: ... on stderr), 2 transport fault. It needs bash and curl, plus jq (or python3) for the JSON.

Python: extension/expservices/bin/expservices_client.py (tested here) #

Standard library only; a module and a command line (expservices_client.py call expsystem::version, page, post, login...).

from expservices_client import Client, ServiceError, TransportError

c = Client("https://www.example.com", jar="expservices.cookies")   # jar optional; keeps the session between runs
c.login("editor", "secret")                                         # POST, stores the new token
version = c.call("expsystem::version")                              # read: returns data
for node in c.pages("expnode::children", 2, limit=50):              # paged read: yields every item
    print(node["name"])
try:
    c.post("expforum::reply", {"topic": 123, "message": "Hello"})   # write: field + header token
except ServiceError as e:                                           # the envelope's error
    print(e.code, e)                                                # 401 login again, 403 policy/token, 422 data
except TransportError as e:                                         # HTTP/network/JSON fault
    print("retry later:", e)

t = Client("https://www.example.com", api_token="expt_...")        # API token variant: no login, no jar, no form token
t.post("expforum::reply", {"topic": 123, "message": "Hello"})       # a POST with the token headers; command line: --token or EXPSERVICES_TOKEN

Kotlin / Android (OkHttp) #

Not compiled here (no Kotlin toolchain on the build box).

// build.gradle: implementation("com.squareup.okhttp3:okhttp:4.12.0"); org.json comes with Android
class Expservices(val site: String) {
    private val jar = HashMap<String, List<Cookie>>()                 // use PersistentCookieJar for a real app
    private val http = OkHttpClient.Builder().cookieJar(object : CookieJar {
        override fun saveFromResponse(url: HttpUrl, cookies: List<Cookie>) { jar[url.host] = cookies }
        override fun loadForRequest(url: HttpUrl) = jar[url.host] ?: emptyList()
    }).build()

    class ServiceException(val code: Int, message: String) : Exception(message)

    private fun url(service: String, args: List<Any> = emptyList()) =
        "$site/ezjscore/call/$service" + args.joinToString("") { "::" + Uri.encode(it.toString()) } + "?ContentType=json"

    private fun send(req: Request): JSONObject {                      // returns the envelope, throws on error
        http.newCall(req).execute().use { r ->
            if (!r.isSuccessful) throw IOException("HTTP ${r.code}")
            val outer = JSONObject(r.body!!.string())
            if (outer.optString("error_text").isNotEmpty()) throw ServiceException(500, outer.getString("error_text"))
            val env = outer.getJSONObject("content")
            if (!env.getBoolean("ok")) env.getJSONObject("error").let { throw ServiceException(it.getInt("code"), it.getString("message")) }
            return env
        }
    }

    // auth
    fun login(user: String, pass: String): JSONObject = send(Request.Builder().url(url("expsession::login"))
        .post(FormBody.Builder().add("username", user).add("password", pass).build()).build())

    // read, with paging
    fun children(nodeId: Int, offset: Int = 0, limit: Int = 25): JSONObject =
        send(Request.Builder().url(url("expnode::children", listOf(nodeId, offset, limit))).build())
    // loop: do { val e = children(2, off); ...; off += 25 } while (e.getJSONObject("meta").getBoolean("has_more"))

    // write with the form token
    fun write(service: String, fields: Map<String, String>): JSONObject {
        val t = send(Request.Builder().url(url("expsession::token")).build()).getJSONObject("data").getString("token")
        val body = FormBody.Builder().add("ezxform_token", t)
        fields.forEach { (k, v) -> body.add(k, v) }
        return send(Request.Builder().url(url(service)).header("X-CSRF-Token", t).post(body.build()).build())
    }
}
// error handling: catch ServiceException (401: show the sign-in screen; 403: refresh the token once; 422: show the message)
// and IOException (offline: retry with backoff). Run it off the main thread (coroutines Dispatchers.IO).

// API token variant: no cookie jar, no login, no form token. Keep the token in the Android Keystore / EncryptedSharedPreferences.
class ExpservicesToken(val site: String, private val token: String) {
    private val http = OkHttpClient()                                   // nothing to keep between calls
    private fun url(service: String, args: List<Any> = emptyList()) =
        "$site/ezjscore/call/$service" + args.joinToString("") { "::" + Uri.encode(it.toString()) } + "?ContentType=json"
    private fun auth(b: Request.Builder) = b.header("Authorization", "Bearer $token").header("X-Exp-Token", token)
    private fun send(req: Request): JSONObject = http.newCall(req).execute().use { r ->
        if (!r.isSuccessful) throw IOException("HTTP ${r.code}")
        val env = JSONObject(r.body!!.string()).getJSONObject("content")
        if (!env.getBoolean("ok")) env.getJSONObject("error").let { throw Expservices.ServiceException(it.getInt("code"), it.getString("message")) }
        env                                                            // 401 here: the token is revoked or expired, ask for a new one
    }
    fun read(service: String, vararg args: Any) = send(auth(Request.Builder().url(url(service, args.toList()))).build())
    fun write(service: String, fields: Map<String, String>): JSONObject {   // POST only, no form token
        val body = FormBody.Builder(); fields.forEach { (k, v) -> body.add(k, v) }
        return send(auth(Request.Builder().url(url(service))).post(body.build()).build())
    }
}

Swift / iOS (URLSession) #

Not compiled here (no Swift toolchain on the build box).

struct ServiceError: Error { let code: Int; let message: String }

final class Expservices {
    let site: URL                                    // https://www.example.com
    let session = URLSession(configuration: .default)   // the default configuration keeps cookies (HTTPCookieStorage.shared)
    init(site: URL) { self.site = site }

    private func url(_ service: String, _ args: [Any] = []) -> URL {
        let tail = args.map { "::" + "\($0)".addingPercentEncoding(withAllowedCharacters: .alphanumerics)! }.joined()
        return URL(string: "\(site)/ezjscore/call/\(service)\(tail)?ContentType=json")!
    }
    private func envelope(_ req: URLRequest) async throws -> [String: Any] {
        let (data, resp) = try await session.data(for: req)
        guard (resp as? HTTPURLResponse)?.statusCode == 200,
              let outer = try JSONSerialization.jsonObject(with: data) as? [String: Any],
              let env = outer["content"] as? [String: Any] else { throw ServiceError(code: 0, message: "transport fault") }
        if env["ok"] as? Bool != true {
            let e = env["error"] as? [String: Any] ?? [:]
            throw ServiceError(code: e["code"] as? Int ?? 500, message: e["message"] as? String ?? "error")
        }
        return env
    }
    private func form(_ url: URL, _ fields: [String: String], token: String? = nil) -> URLRequest {
        var r = URLRequest(url: url); r.httpMethod = "POST"
        var f = fields; if let t = token { f["ezxform_token"] = t; r.setValue(t, forHTTPHeaderField: "X-CSRF-Token") }
        var c = URLComponents(); c.queryItems = f.map { URLQueryItem(name: $0.key, value: $0.value) }
        r.httpBody = c.percentEncodedQuery?.data(using: .utf8)
        r.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type"); return r
    }

    func login(_ user: String, _ pass: String) async throws -> [String: Any] {          // auth
        try await envelope(form(url("expsession::login"), ["username": user, "password": pass]))
    }
    func children(_ node: Int, offset: Int = 0, limit: Int = 25) async throws -> [String: Any] {   // read, paged
        try await envelope(URLRequest(url: url("expnode::children", [node, offset, limit])))     // meta.has_more drives the next page
    }
    func write(_ service: String, _ fields: [String: String]) async throws -> [String: Any] {     // write
        let t = ((try await envelope(URLRequest(url: url("expsession::token"))))["data"] as! [String: Any])["token"] as! String
        return try await envelope(form(url(service), fields, token: t))
    }
}
// Errors: catch ServiceError (401 sign in, 403 refresh token once, 422 show message); other errors are transport faults.

// API token variant: no cookies, no login, no form token. Keep the token in the Keychain.
final class ExpservicesToken {
    let site: URL, token: String
    let session = URLSession(configuration: { let c = URLSessionConfiguration.ephemeral; c.httpCookieStorage = nil; return c }())
    init(site: URL, token: String) { self.site = site; self.token = token }

    private func request(_ service: String, _ args: [Any] = [], form: [String: String]? = nil) -> URLRequest {
        let tail = args.map { "::" + "\($0)".addingPercentEncoding(withAllowedCharacters: .alphanumerics)! }.joined()
        var r = URLRequest(url: URL(string: "\(site)/ezjscore/call/\(service)\(tail)?ContentType=json")!)
        r.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        r.setValue(token, forHTTPHeaderField: "X-Exp-Token")
        if let f = form {                                              // a write: POST, no form token
            var c = URLComponents(); c.queryItems = f.map { URLQueryItem(name: $0.key, value: $0.value) }
            r.httpMethod = "POST"; r.httpBody = c.percentEncodedQuery?.data(using: .utf8)
            r.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
        }
        return r
    }
    func call(_ service: String, _ args: [Any] = [], form: [String: String]? = nil) async throws -> [String: Any] {
        let (data, resp) = try await session.data(for: request(service, args, form: form))
        guard (resp as? HTTPURLResponse)?.statusCode == 200,
              let env = (try JSONSerialization.jsonObject(with: data) as? [String: Any])?["content"] as? [String: Any]
        else { throw ServiceError(code: 0, message: "transport fault") }
        if env["ok"] as? Bool != true {                               // 401: the token is revoked or expired
            let e = env["error"] as? [String: Any] ?? [:]
            throw ServiceError(code: e["code"] as? Int ?? 500, message: e["message"] as? String ?? "error")
        }
        return env
    }
}

Objective-C (NSURLSession) #

Not compiled here (no Objective-C compiler or Foundation on the build box; gcc has no Objective-C front end).

// The shared session keeps cookies. Wrap in a method taking a completion block; shown here for one write.
- (void)post:(NSString *)service fields:(NSDictionary<NSString *, NSString *> *)fields
  completion:(void (^)(NSDictionary *data, NSError *error))done {
    NSString *base = @"https://www.example.com/ezjscore/call/";
    NSURL *tokenURL = [NSURL URLWithString:[base stringByAppendingString:@"expsession::token?ContentType=json"]];
    [[NSURLSession.sharedSession dataTaskWithURL:tokenURL completionHandler:^(NSData *d, NSURLResponse *r, NSError *e) {
        NSDictionary *env = [NSJSONSerialization JSONObjectWithData:d options:0 error:nil][@"content"];   // d nil = transport fault
        if (e || ![env[@"ok"] boolValue]) { done(nil, e ?: [self errorFrom:env]); return; }
        NSString *token = env[@"data"][@"token"];
        NSMutableArray *pairs = [NSMutableArray arrayWithObject:[@"ezxform_token=" stringByAppendingString:token]];
        [fields enumerateKeysAndObjectsUsingBlock:^(NSString *k, NSString *v, BOOL *s) {
            [pairs addObject:[NSString stringWithFormat:@"%@=%@", k,
                [v stringByAddingPercentEncodingWithAllowedCharacters:NSCharacterSet.alphanumericCharacterSet]]];
        }];
        NSString *u = [NSString stringWithFormat:@"%@%@?ContentType=json", base, service];
        NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:u]];
        req.HTTPMethod = @"POST"; req.HTTPBody = [[pairs componentsJoinedByString:@"&"] dataUsingEncoding:NSUTF8StringEncoding];
        [req setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
        [req setValue:token forHTTPHeaderField:@"X-CSRF-Token"];
        [[NSURLSession.sharedSession dataTaskWithRequest:req completionHandler:^(NSData *d2, NSURLResponse *r2, NSError *e2) {
            NSDictionary *env2 = d2 ? [NSJSONSerialization JSONObjectWithData:d2 options:0 error:nil][@"content"] : nil;
            done([env2[@"ok"] boolValue] ? env2[@"data"] : nil, e2 ?: ([env2[@"ok"] boolValue] ? nil : [self errorFrom:env2]));
        }] resume];
    }] resume];
}
- (NSError *)errorFrom:(NSDictionary *)env {      // { ok:false, error:{ code, message } } -> NSError (domain "expservices")
    NSDictionary *err = env[@"error"];
    return [NSError errorWithDomain:@"expservices" code:[err[@"code"] integerValue]
                           userInfo:@{NSLocalizedDescriptionKey: err[@"message"] ?: @"transport fault"}];
}
// Login: the same POST without token to expsession::login with username and password (cookies are kept by the session).
// Read with paging: GET .../expnode::children::2::<offset>::<limit>, continue while env[@"meta"][@"has_more"] is true.

// API token variant: no cookies, no token fetch; the same POST without ezxform_token and with the token headers.
- (NSMutableURLRequest *)requestFor:(NSString *)service token:(NSString *)token {
    NSString *u = [NSString stringWithFormat:@"https://www.example.com/ezjscore/call/%@?ContentType=json", service];
    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:u]];
    req.HTTPShouldHandleCookies = NO;                                       // the token is the only credential
    [req setValue:[@"Bearer " stringByAppendingString:token] forHTTPHeaderField:@"Authorization"];
    [req setValue:token forHTTPHeaderField:@"X-Exp-Token"];
    return req;       // for a write set HTTPMethod = @"POST", the form body and the Content-Type as above (no ezxform_token)
}
// Run it with [[NSURLSession sessionWithConfiguration:NSURLSessionConfiguration.ephemeralSessionConfiguration] dataTaskWithRequest:...];
// keep the token in the Keychain. A 401 envelope means the token is revoked or expired.

Qt / C++ (QNetworkAccessManager) #

Not compiled here (no Qt headers or qmake on the build box).

// QT += network. One QNetworkAccessManager per client; set a QNetworkCookieJar (the default one keeps session cookies).
class Expservices : public QObject {
    Q_OBJECT
    QNetworkAccessManager net; QString site = "https://www.example.com"; QString token;
    QUrl url(const QString &svc, const QStringList &args = {}) const {
        QString u = site + "/ezjscore/call/" + svc;
        for (const QString &a : args) u += "::" + QString::fromUtf8(QUrl::toPercentEncoding(a));
        return QUrl(u + "?ContentType=json");
    }
    // Parses the answer; emits failed(code, message) for { ok:false }, for a non-200 status or a body that is not JSON.
    void handle(QNetworkReply *r, std::function<void(const QJsonObject &)> ok) {
        connect(r, &QNetworkReply::finished, this, [=] {
            const QByteArray body = r->readAll(); const int http = r->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
            r->deleteLater();
            const QJsonObject env = QJsonDocument::fromJson(body).object().value("content").toObject();
            if (r->error() != QNetworkReply::NoError && http != 200) { emit failed(0, r->errorString()); return; }   // transport
            if (!env.value("ok").toBool()) { const auto e = env.value("error").toObject();
                emit failed(e.value("code").toInt(500), e.value("message").toString()); return; }                  // service
            ok(env);
        });
    }
public:
    void login(const QString &user, const QString &pass) {                        // auth: POST, no token needed
        QNetworkRequest rq(url("expsession::login"));
        rq.setHeader(QNetworkRequest::ContentTypeHeader, "application/x-www-form-urlencoded");
        QUrlQuery q; q.addQueryItem("username", user); q.addQueryItem("password", pass);
        handle(net.post(rq, q.toString(QUrl::FullyEncoded).toUtf8()), [this](const QJsonObject &env) {
            token = env["data"].toObject()["token"].toString(); emit signedIn(env["data"].toObject()); });
    }
    void children(int node, int offset, int limit) {                              // read, paged
        handle(net.get(QNetworkRequest(url("expnode::children", {QString::number(node), QString::number(offset), QString::number(limit)}))),
               [this](const QJsonObject &env) { emit page(env["data"].toArray(), env["meta"].toObject()["has_more"].toBool()); });
    }
    void write(const QString &svc, const QMap<QString, QString> &fields) {         // write: field + header token
        QNetworkRequest rq(url(svc));
        rq.setHeader(QNetworkRequest::ContentTypeHeader, "application/x-www-form-urlencoded");
        rq.setRawHeader("X-CSRF-Token", token.toUtf8());
        QUrlQuery q; q.addQueryItem("ezxform_token", token);
        for (auto it = fields.begin(); it != fields.end(); ++it) q.addQueryItem(it.key(), it.value());
        handle(net.post(rq, q.toString(QUrl::FullyEncoded).toUtf8()), [this](const QJsonObject &env) { emit written(env["data"]); });
    }
signals: void failed(int code, const QString &message); void signedIn(const QJsonObject &); void page(const QJsonArray &, bool more); void written(const QJsonValue &);
};
// The token comes from the login answer; after a 403 fetch expsession::token once and retry once.

// API token variant: no login, no cookie jar needed, no form token. Keep the token in KWallet / libsecret.
class ExpservicesToken : public Expservices {
    QString apiToken;
public:
    explicit ExpservicesToken(const QString &t) : apiToken(t) {}
    QNetworkRequest authorised(QNetworkRequest rq) const {
        rq.setRawHeader("Authorization", "Bearer " + apiToken.toUtf8());
        rq.setRawHeader("X-Exp-Token", apiToken.toUtf8());
        return rq;
    }
    // read: net.get(authorised(QNetworkRequest(url("expsession::whoami"))));
    // write: rq = authorised(QNetworkRequest(url(svc))); content type form-urlencoded; net.post(rq, body) with the fields only (no ezxform_token)
    // a { ok:false, error:{ code:401 } } answer means the token is revoked or expired: ask the user for a new one
};

GTK / Python (requests, or libsoup) (tested here: both variants run against the live site) #

With PyGObject, run the calls off the main loop (GLib.idle_add or a thread) and hand the data to the widgets. requests is the simplest transport; the shell/Python client above has the same logic without it.

import http.cookiejar
import requests
from gi.repository import GLib

class Api:
    def __init__(self, site): self.site, self.s, self.token = site, requests.Session(), None   # Session keeps cookies
    def _url(self, svc, args=()): return f"{self.site}/ezjscore/call/{svc}" + "".join("::" + requests.utils.quote(str(a), safe="") for a in args) + "?ContentType=json"
    def _env(self, r):
        r.raise_for_status()                                  # transport fault: HTTPError
        env = r.json()["content"]
        if not env["ok"]: raise RuntimeError(f'{env["error"]["code"]}: {env["error"]["message"]}')
        return env
    def login(self, u, p): env = self._env(self.s.post(self._url("expsession::login"), data={"username": u, "password": p})); self.token = env["data"]["token"]; return env["data"]
    def read(self, svc, *args): return self._env(self.s.get(self._url(svc, args)))            # paged: args end with offset, limit
    def write(self, svc, **fields):
        self.token = self.token or self.read("expsession::token")["data"]["token"]
        return self._env(self.s.post(self._url(svc), data={"ezxform_token": self.token, **fields}, headers={"X-CSRF-Token": self.token}))

# in a handler: threading.Thread(target=lambda: GLib.idle_add(fill_list, api.read("expnode::children", 2, 0, 25)["data"])).start()

class TokenApi(Api):                                    # API token variant: no login, no cookies, no form token
    def __init__(self, site, token):
        super().__init__(site)
        self.s.cookies.set_policy(http.cookiejar.DefaultCookiePolicy(allowed_domains=[]))   # keep no cookie
        self.s.headers.update({"Authorization": "Bearer " + token, "X-Exp-Token": token})
    def write(self, svc, **fields): return self._env(self.s.post(self._url(svc), data=fields))   # POST, no ezxform_token

libsoup (Soup 3): Soup.Session() keeps cookies when a Soup.CookieJar feature is added (session.add_feature(Soup.CookieJar())); Soup.Message.new_from_encoded_form("POST", url, Soup.form_encode(...)) builds the POST, msg.get_request_headers().append("X-CSRF-Token", token) adds the header, and session.send_and_read_async(msg, ...) returns the bytes of the same { error_text, content } JSON.

KDE and GNOME integration notes #

• KDE (Qt/KF6). Use the Qt client above. Store the password in KWallet (KWallet::Wallet::openWallet) and never in the config file; only the session cookie lives in memory (or QNetworkCookieJar persisted to ~/.cache). Show the services of the catalogue as a KRunner plugin (query expsearch::search), a Plasma widget (read services on a timer, expsession::ping keeps the session), or KIO slave-like browsing of expnode::children. KJob/QNetworkReply give the async model; KNotification for 401 ("sign in again").
• GNOME (GTK4/libadwaita). Use the GTK/Python client or Soup 3 from C/Vala/Rust. Store the password with libsecret (Secret.password_store_sync); show the services in a GNOME Shell search provider (D-Bus org.gnome.Shell.SearchProvider2 backed by expsearch::search), a libadwaita app with an Adw.NavigationView per node level, Gio.ListStore filled page by page. Gio.Task/GLib.idle_add keep the UI responsive; GNotification for 401.
• Both. Discover with expservices::catalog at start (cache by expservices::version), build forms from the args of a write service, send writes only after the user's action, and treat every 403 as "refresh the token once". Online accounts: KDE (KAccounts) and GNOME (GOA) have no generic "cookie session" provider, so keep the account in the app.

Tests #

The shell and Python clients were run against a live site (read-only calls; the write path up to the 401 an anonymous session gets). The API token flow was checked over HTTP (create, bearer read and write, revoke, 401), the shell and Python clients were driven with a token, and the GTK/Python snippets of this guide were extracted and run.

Frontend designs: React and wireframe #

Both are designs of the extension (extension/expservices/design/), shown by test siteaccesses and reached by URI:

No build step; vendored libraries. The React design needs no Node, JSX or bundler: its code is ES modules (javascript/portal/) using React.createElement (h). The libraries are vendored into the design (javascript/vendor/, stylesheets/vendor/) so the site works offline and the versions cannot move under it: React and ReactDOM 18.3.1 (UMD) and React Bootstrap 2.10.2 from cdnjs.cloudflare.com/ajax/libs/ and Bootstrap 5.3.3 CSS. To upgrade, download the same file names from cdnjs at the new version. Layout: services.js (the client: fetch, session cookie, form token, envelope unwrapping, ServiceError), api.js (one function per screen need, the only file that names services), ui.js (kit shortcuts, useAsync, pager, error and loading states), pages/*.js (one component per page), app.js (shell and hash router).

Siteaccesses. portalreact and portalwireframe are directories settings/siteaccess/<name>/site.ini.append.php (SiteDesign = the design, IndexPage=user/login so the shell renders with a 200) plus the entry AvailableSiteAccessList[]=<name> in the global override, added with exp:ini add site/SiteAccessSettings/AvailableSiteAccessList[] <name> override. Reverse it with exp:ini rem for the same entry and removing the directory; the live site siteaccess is not touched. The extension registers its designs with settings/design.ini.append.php (DesignExtensions[]=expservices); without that file an extension design is not found.

Frontends: jQuery 4 reference and reactive jQuery #

Two portal designs in extension/expservices/design/ consume the services from the browser. Both are corporate portals (home, news list and article, shop catalogue, product and basket, forums with topics and replies, media gallery, feeds, search, login and profile), rendered client-side, with no build step, on the jQuery 4 that ezjscore ships (ezjsc::jquery). Both are accessible (skip link, landmarks, aria-live announcements, focus moved to the page on navigation, labelled forms, native <dialog> for the lightbox), responsive (mobile first, one breakpoint at 48em) and light or dark (prefers-color-scheme, plus a toggle remembered in localStorage).

Architecture (expportal_jquery) #

templates/pagelayout.tpl is the only template. It ignores the module result, prints the page frame, passes the configuration as data- attributes of <body> (siteaccess URL, ezjscore/call URL, content root node ids from extension/expservices/settings/expportal.ini), loads jQuery 4 through ezscript_load( 'ezjsc::jquery' ) and then the scripts in javascript/portal/, one per feature:

The address is the hash route (#/news/12), so every portal URL is served by the one pagelayout and the portal can be dropped under any siteaccess. api.call( feature, args, post ) builds <siteaccess>/ezjscore/call/<service>::<arg>::<arg>?ContentType=json, sends reads as GET and writes as POST with the form token (expsession::token, field ezxform_token, header X-CSRF-Token; the login is the one write sent without it), unwraps { error_text, content } and the service envelope { ok, data, meta }, and rejects with { code, message }. At boot it reads expservices::catalog: a service that is not in the catalogue is not called and its page shows a clear "service not available" state instead of an error; if the catalogue itself cannot be read, calls are tried and a 404 or "no such function" answer gets the same state.

The reactive variant (expportal_reactive) #

It falls back to expportal_jquery (AdditionalSiteDesignList), so core.js (api, services, router, theme) and portal.css are shared. Its own scripts in javascript/reactive/ implement the pattern, documented in each file:

state --(components)--> description --(vdom: keyed diff)--> DOM
  ^                                                            |
  |   dispatch( action ) <--------- event handlers ------------+
  +--- reducer( state, action ) -> new state;  effects run after the reducer and call services

A page never fetches: the route reducer stores the route, the effect reads the route table's needs and loads the missing resources into state.res[ key ] (loading, ok, error, unavailable), the component reads that and draws.

How each page maps to services #

The one table is ExpPortal.services in core.js; ExpPortal.argMap turns the portal's ( node, offset, limit ) into the positional order of a service. To follow a renamed service, change the table only.

Forum, feed, search and profile services were not yet in the catalogue when the designs were written; their names are the contract names and those pages show the "not available" state until the services exist. Content root node ids (news, shop, forums, media) are in expportal.ini; the defaults are the content root (2) and Media (43).

How to run #

The test siteaccesses are local settings (not committed): create settings/siteaccess/portaljq and portalreactive and add them to [SiteAccessSettings] AvailableSiteAccessList of the global override with exp:ini (reversible: delete the two directories, and php bin/php/console exp:ini rem 'site/SiteAccessSettings/AvailableSiteAccessList[]' <name> override). They match by URI, so open https://www.example.com/portaljq/ and https://www.example.com/portalreactive/; the live site siteaccess and its design are untouched. DefaultPage is user/login because that module answers 200 to anonymous users and the pagelayout replaces its output; Velocity workers need a restart to see a new siteaccess, Apache/FPM do not.

Tests #

A browser test runs both portals at 960 px with device scale 2 and at 390 px: every page renders its heading and no unfinished state, the menu (and the phone menu toggle) navigates, search and the theme toggle work, no horizontal scroll, no console error and no jQuery Migrate warning (the code is jQuery 4 clean: no $.isArray, $.trim and the like). In-page unit tests cover the core (node shapes, list folding, URL building, unavailable handling, text safety) and, for the reactive design, keyed reordering with node identity kept, handler replacement, text safety, the store (reducer, subscribe on change only, effects) and the route table. expui's browser harness (/expui/test) is an admin page tied to admin sessions, so the portal tests run in the Playwright page instead.

Users and access (nine domains, 195 services) #

Classes in extension/expservices/classes/users/, tests in tests/tests/extension/expservices/users/ (113 tests, run against the live database; they create a test group, test users, a test role, test sessions and collaboration items and remove them again). Users are addressed by content object id, user groups by node id, roles and policies by id.

Rules that hold for every service of these domains:

• Nothing returns a password hash, activation or reset key, session key or session data. Login, e-mail and account state of a user are only returned for oneself or for a user the caller may edit (content/edit on the user object); other callers get the public part (id, name, node, class).
• Writes are POST with the form token (expsession::token), checked against the policy shown in the table, and recorded as service.<domain>.<method> plus, where the kernel records one, its own access.* event (role, policy, user, password and reset events are written by the kernel code the services call).
• Roles are edited like the role editor does: exprole::draftCreate, draftAddPolicy, draftRemovePolicy, publish (or draftDiscard); exppolicy changes the published role directly and validates module, function and limitation names against the module definition.
• expaccount carries the public flows. The reset and activation keys travel by e-mail only; an activation key expires after 24 hours, a reset key after site.ini [UserSettings] ForgotPasswordKeyLifetime (one hour as shipped), both through the services as on the forgot-password page; forgotRequest answers the same for known and unknown addresses. Where a write is open to visitors its access is the login or registration policy of the user module (the catalogue allows no public write).
• A collaboration item is visible to its participants only (everybody else gets 404); approve and deny need the approver role and a waiting approval, and leave the workflow to resume exactly as the kernel's own view does.
• expsessionadmin names a session by a short derived identifier; listing and ending other sessions needs setup/administrate. Session counts read the ezsession table, which is empty when the PHP file session handler is used (expsessionadmin::settings says which handler is active). With great power comes great responsibility.

expuser (42 services) #

expusergroup (20 services) #

exprole (26 services) #

exppolicy (16 services) #

expsessionadmin (16 services) #

exppreferences (13 services) #

expnotification (21 services) #

expcollaboration (22 services) #

expaccount (19 services) #

Total: 195 services.

Commerce, community and feeds (16 domains, 256 services) #

Classes in extension/expservices/classes/commerce/ and classes/community/, tests in tests/tests/extension/expservices/commerce/ and community/ (151 tests, run against the live database like the other domains: test products, forums, polls, forms and exports are created in a test folder under the Media root (node 43) or as named test rows and removed in tearDown; baskets exist only for a test session key; the checkout tests create the temporary order of a test basket and cancel it, no order is completed and no payment is created; there is never a test database). Run: php vendor/bin/phpunit tests/tests/extension/expservices/commerce/ tests/tests/extension/expservices/community/.

Rules that hold for every service of these domains:

• The shop works on the kernel. Products are content objects whose class has a price attribute (ezprice, ezmultiprice; expproduct::classes). Prices come with and without VAT, with the discount of the product and, when a currency is asked for (USD, EUR ...), converted with the rates of the currency table (in_currency; null when a rate is missing). Basket, wish list, orders, VAT, currency, discount and payment services call eZBasket, eZOrder, eZVatType/eZVatRule, eZCurrencyData, eZDiscountRule, eZWishList, eZPaymentObject and the shop operations (addtobasket, confirmorder, checkout), so workflows, triggers and the kernel's own audit events (commerce.order.status, .archive, .unarchive, .delete, commerce.vat.change, .currency.change, .discount.change, .payment.approve, .basket.checkout) behave exactly as in the shop views.
• The basket belongs to the session. A remote app keeps its session cookie (expsession::login); without one, reads answer an empty basket and writes answer 401. Checkout is in steps: checkoutStatus (what blocks), startCheckout (the temporary order, nothing charged), review (shipping and VAT as the confirm step), cancelCheckout, and, only when the client means it, placeOrder, which runs the checkout operation: it activates the order or hands over to the payment gateway (redirect_url). Nothing else completes an order.
• Orders: a customer reads their own (exporder::mine, myOrder, myReceipt); the shop administrators (shop/administrate) list, view, search, archive, unarchive and delete any order, change the status within their shop/setstatus policy (FromStatus/ToStatus limitations are applied by statusOptions and setStatus) and read statistics, customers and the dashboard. Account data is returned by exporder::account for administrators only; card or account numbers are never stored by the kernel and never returned.
• Money values are numbers rounded to four decimals, VAT percentages numbers, currencies three-letter codes, times ISO 8601 in UTC.
• Forums, topics, replies, comments, reviews and polls are content services over the classes configured in settings/expservices.ini [Community] (ForumClass=forum, TopicClass=forum_topic, ReplyClass=forum_reply, CommentClass=comment, PollClass=poll, ReviewClass=review, TopicStickyAttribute=sticky), so a site with other class identifiers changes the INI, not the code. Create, edit and remove follow the content policies of the caller (the owner limitation lets members edit and remove their own posts); the text fields of a class are written as POST fields of the attribute's name or as one fields JSON object (rich text attributes take plain text and store paragraphs); unknown fields are refused (422), required ones checked. Moderation is hide/unhide (policy content/hide), hidden lists the hidden comments, a sticky topic stays on top, a topic can be moved to another forum. Removal goes to the trash.
• Collected forms and polls use the information collection of the kernel. expinfocollection::submit does what content/collectinformation does (validation by the datatype, anonymous collection and unique/overwrite/multiple handling from collect.ini) for text, number, boolean and choice fields; reading, summary, CSV export and removal need the infocollector/read policy (the CSV neutralises formulas). A poll vote is one collection: exppoll::vote answers the results; the poll class is unique per user in the standard collect.ini.
• Feeds: expfeed::exports and output serve the RSS exports of the site as the reader gets them (RSS 1.0, 2.0, Atom, OPML, iTunes; data.content_type and data.content), rss, atom and json build RSS 2.0, Atom 1.0 and JSON Feed 1.1 of the newest content below any node the caller may read (classes limits the classes, limit is capped at 100), discover lists the feed addresses for a node. Export management (rss/edit) creates active exports directly (the draft/publish copy of the admin editor is not used); RSS imports are read (imports, importStatus, importCheck) and switched (importSetActive); runImport (rss/edit, POST) runs one import with the code of the rssimport cronjob (fetch, create and publish the new items below the destination, once per item, known by the item's link or guid) and answers found, new, created and one line per item (imported, would_import, exists, no_identifier, skipped_max_items) plus the log the cronjob would print. With dry_run=1 nothing is created: it only reports what would be imported. max_items limits the new items of one run (0 = all). The caller also needs the right to create below the destination node, a draft import cannot run (409), and importCheck and runImport fetch only http/https addresses. A real run records data.import.rss as the cronjob does, besides service.feed.runimport.
• Writes are POST with the form token (expsession::token) and recorded as service.<domain>.<method>; where the kernel records its own event for the change, it is recorded as well.
• Known kernel fault, worked around: eZVatRule::removeVatRule() calls an instance method statically, which PHP 8 refuses; expvat::removeRule and removeType remove the rules themselves (with the same audit event).

Shop #

Products (expproduct, 19 services) #

Basket and checkout (expbasket, 25 services) #

Orders (exporder, 24 services) #

VAT (expvat, 19 services) #

Currencies (expcurrency, 19 services) #

Discounts (expdiscount, 16 services) #

Wish lists (expwishlist, 11 services) #

Shipping (expshipping, 8 services) #

Payments (exppayment, 10 services) #

Forms, polls and community #

Collected forms (expinfocollection, 12 services) #

Polls (exppoll, 11 services) #

Forums (expforum, 13 services) #

Topics (exptopic, 17 services) #

Replies (expreply, 13 services) #

Comments and reviews (expcomment, 17 services) #

Feeds #

Feeds (expfeed, 22 services) #

Total: 256 services in 16 domains (84 writes).

Content services: 350 services in 15 domains (112 writes) #

Written by the content part of expservices: extension/expservices/classes/content/ (one class per domain over the shared expContentServiceBase: fetch helpers with the access checks, the exporters that turn nodes, objects, versions, classes, sections and states into plain arrays, attribute values per datatype, sort and filter parsing, and the now-or-job routing). Tests: tests/tests/extension/expservices/content/ (live database like the other domains: reads on the stable nodes, writes on test content under the Media root node 43 and on test classes, class groups, sections, state groups, aliases and wildcards that tearDown removes; never a test database). The sample calls were also verified over HTTP on Apache with a signed-in admin session (reads, a refused write without the token, then create, update and remove of a test folder).

How the content services work, beyond the rules above:

• Policies with limitations. The access column is the policy the call needs at all (content/read, content/edit, ...); inside, every call checks the node or object the way the kernel does (canRead, canEdit, canRemove, canMoveFrom, canCreateClassList, canAssignSectionToObject, the allowed state list ...), so a limitation by class, section, subtree, owner or state applies to the services as it does in the admin. Lists use the kernel fetch functions with their permission SQL, so a user only counts and pages what they may read.
• Identifiers. Nodes, objects, versions, sections and states are addressed by number; classes by id or identifier; state groups by id or identifier; languages by locale code (eng-GB).
• Attribute input. Writes take attribute values as a JSON object identifier => string, in the string form the datatype reads (fromString(): see expattribute::string). Datatypes whose string form is a file path or a credential (ezimage, ezbinaryfile, ezmedia, ezuser, ezpassword) are refused with 422: a remote caller must never make the server read a local path. Required attributes must be given on create. Values come back per datatype (text, number, boolean, date with ISO form, XML text as xml and html, relations as ids, images with their original URL).
• Lists answer the paged envelope (data items, meta total, offset, limit, count, has_more). Node lists take sort (path, published, modified, section, depth, class_identifier, class_name, priority, name, modified_subnode, node_id, contentobject_id), order (asc, desc), limit, offset and a JSON filter: class[], exclude_class[], section, state[], owner, name (prefix), language, from and to (published), depth, hidden.
• Now or job. Large operations (move, copy of a subtree, hide, reveal, remove of subtrees, section and state of a subtree, add and remove locations) take the POST field mode: now runs in the request (refused above content.ini NowLimit nodes, answer 422), job creates a content job and starts its worker, auto (the default) picks by SynchronousLimit. A job answer is { job_id, type, state, spawned } with meta.mode = job; follow it with expcontentjob::progress::<job_id>. A subtree locked by a running job answers 409 to a synchronous write.
• Drafts of classes are the temporary version of the class, the one the admin class editor works on: editDraft or createDraft, change, then publishDraft (the class edit handler updates existing objects) or discardDraft.
• Removal. remove takes move_to_trash (default 1); the root nodes cannot be removed; exptrash::purge, purgeMany and emptyTrash (POST confirm=yes) remove for good through the kernel trash service. Classes with objects, sections in use, state groups with the ez prefix and the last location of an object are refused with 409 or 403.
• Audit. Every successful write records service.<domain>.<method>; the kernel records its own content.* events for the operations the services call (create, publish, move, remove, section, state, translation, class, URL alias).

Errors: 400 bad argument, 401 not signed in, 403 denied (policy, method or form token), 404 not found, 409 conflict (exists, locked, in use), 422 not valid (input refused by a datatype or a rule).

Example: create an article, change it, and follow a large move as a job (shell, after expsession::login):

curl -b jar -c jar --data-urlencode 'class=article' --data-urlencode 'attributes={"title":"Hello","intro":"First"}' \
     --data-urlencode "ezxform_token=$TOKEN" "$BASE/ezjscore/call/expnode::create::43?ContentType=json"
curl -b jar -c jar --data-urlencode 'attributes={"title":"Hello again"}' --data-urlencode "ezxform_token=$TOKEN" \
     "$BASE/ezjscore/call/expnode::update::<node>?ContentType=json"
curl -b jar -c jar --data-urlencode 'mode=job' --data-urlencode "ezxform_token=$TOKEN" \
     "$BASE/ezjscore/call/expnode::move::<node>::<new-parent>?ContentType=json"      # { job_id: ... }
curl -b jar "$BASE/ezjscore/call/expcontentjob::progress::<job_id>?ContentType=json"

Nodes (expnode, 49 services, 16 writes) #

The content tree: fetch by id, remote id, path and object; children and subtrees paged, sorted and filtered; counts, ancestors, siblings, data maps, rights; create, update, move, copy, hide, swap, remove, sort and priority.

Objects (expobject, 36 services, 11 writes) #

Content objects: lists by class and owner, data maps and attributes with their values, names, owner, class, section, states, locations, languages; create, update (a new published version), rename, owner, languages, copy, remove.