JSON endpoints 

How they are addressed 

The endpoints are a PAGE object of their own, keyed on a page type. They answer on whichever page the edit plugin sits on, so no page has to be created for them.

The page object renders the Extbase plugin Ajax of the extension directly, with config.disableAllHeaderCode = 1 so the body is exactly what the action produced, and config.no_cache = 1. view.formatToPageTypeMapping.json is set to the same number.

The map carries eight entries: save, saveField, addChild, removeChild, reorderChildren, setChildVisibility, uploadImage and removeImage. read is deliberately not among them. When the page type is 0 the map is empty.

The endpoints 

All of them are POST. All of them except uploadImage take a JSON object as the request body.

The value types are checked strictly, and a value of the wrong type is a 400 rather than something that is cast:

uid is required by every endpoint except read, and it is only ever a filter: the set of records a request may reach is resolved from the session, and a uid outside that set is answered like a uid that does not exist.

The request token 

Every writing endpoint requires a TYPO3 request token in the X-TYPO3-RequestToken header. It is a hash signed JWT bound to a nonce cookie of that browser, with the scope

modern_extbase_frontend_edit/record-save

A token that is missing, that cannot be verified, or that carries a different scope is refused identically. The token is proof that the browser loaded a page of this site; it is not authorisation, and it does not replace the login check.

The __RequestToken body parameter TYPO3 also accepts is not usable here: it is read from the parsed request body, which is empty for a request carrying a JSON body.

read requires no token and no login. It changes nothing, and answering an anonymous caller differently from a logged-in non-owner would say which profiles exist.

The guards, in order 

For a writing endpoint with a JSON body, each check runs before any value of the request body is looked at:

read runs steps 1, 2, 6 and 7 only. uploadImage replaces step 2 with multipart/form-data and adds a check that exactly one file was sent; its order is otherwise the same.

The response envelope 

Every response carries a JSON body and the content type application/json; charset=utf-8 — successes and failures alike.

A success is 200 and one key:

{
    "data": {}
}

data is the whole profile as it stands after the write, not an echo of the request, and it is the same document for every endpoint — including the ones that changed a single field.

A failure carries one key as well:

{
    "errors": [
        {
            "code": 1786495903,
            "message": "Request token missing or invalid."
        }
    ]
}

code is a TYPO3 style exception code identifying the one line that refused the request. message is written for a developer, is not localized, and never repeats a value the request carried.

A 422 uses the same key with one entry per rejected value, and those entries carry a field:

{
    "errors": [
        {
            "field": "shortname",
            "code": 1221560718,
            "message": "Enter a short name."
        }
    ]
}

field is the name of the rejected field, or null for an error that belongs to the record rather than to one of its fields. A rejected image upload is keyed under image. The message of a validation error is localized: it comes from the label file and is already translated and substituted.

The profile document 

The object under data, and the same document the edit plugin renders into its markup:

Both collections contain the records the owner has hidden, marked by their hidden flag. That is what lets an owner find and publish them again.

Status codes