General Configuration of APIs

Access to the configuration of an API is via the HTTP/POST endpoint /schema/<namespace>/<api>. The configuration itself is transmitted in JSON format.

POST creates a new API — if it already exists, an error (400) is triggered. When creating, the account used is noted as the owner of the API.
DELETE removes an existing API — all associated records are irreversibly removed.
PUT modifies an existing API — if it does not exist, an error (400) is triggered. The records are not changed; if a migration is necessary, it must be carried out appropriately — e.g. first import a common (old & new) configuration, adjust records, bring configuration to the final state. This can be more or less complex and is currently not addressed.
GET reports the current configuration of an API.

The CMS offers further HTTP/GET queries:

/schema reports all namespaces (array of strings) where the account is allowed to see at least one API. A restriction (filter) or sorting is not provided — all namespaces are always reported.
/schema/tutorial returns all APIs (array of strings) in a namespace (here tutorial) to which the account has at least read rights. The list of APIs is not sorted.

The basic structure of a configuration looks as follows:

{
    "fields": {
        "prop1": { "type": "type1" },
        "prop2": { "type": "type2" ),
        ...
    },
    "hideId": true,
    "previewUrl": "https://www.preview.net?ns={namespace}&api={api}&id={id}&lang={language}"
}

Here an API would be defined with records where each record has two mandatory fields: prop1 uses data type type1, prop2 the type2.

In the example, in addition to the structural description, further optional parameters are specified that are evaluated by the generic maintenance application / CMS frontend:

hideId can be set (true) to suppress the display of the internal, automatically created unique identifier (_id).
singleton is used for APIs (true) that may only contain a single record — often used for configurations. If no record has yet been entered in the API, only a button for creating the first and only record is offered in the maintenance interface. Once such a record exists, it is offered directly for editing when the API is called in the maintenance interface. Actually it can be deleted again, whereby the next call will again offer the button for creating — the CMS does not allow more than one record to be created.
previewUrl leads, if present, to a preview button for a record being displayed in the editing view of a record in the CMS frontend. When calling the configured preview URL, the placeholder shown in curly braces is replaced (namespace, api, id, and language) — not all placeholders need to be used. Example for a concrete call of the previewUrl¹: https://www.preview.net/?ns=tutorial&api=stringonly&id=4381dc2c-0ca4-4b05-86c2-212ca14962df.

https://www.preview.net is only a fictitious example. To be able to see a preview, your own server must be running that has knowledge of and access to the CMS and retrieves the data for the requested record from the CMS each time to then be able to display it. ↩

Footnotes​

Footnotes