Design guidelines¶

Each cockpit module has its own helpers implementing a set API to read and write the configuration and to execute actions. All helpers are saved inside /usr/libexec/nethserver/api/<controller_name>/ directory.

Each helper:

must be an executable file, it can be written in any language depending on the task Example: /usr/libexec/nethserver/system-openssh/read.
uses JSON format for input and output; the JSON can must be read as input from STDIN and printed to STDOUT
can use other helpers to execute multiple actions, the helpers can be placed in the same directory (eg. /usr/libexec/nethserver/openssh/help1-read)

The JavaScript controller uses the cockpit.spawn method to communicate with the backend. After spawning the process, the controller gather the standard output to track the task progress.

At the end, the process exit code will raise an error or a success.

Example:

process = cockpit.spawn("/usr/libexec/nethserver/system-status/read", { ... }

Methods¶

APIs should implement classical CRUD operations:

create
read
update
delete

Extra operations:

validate
execute
hints

None of the above action is mandatory.

create¶

Create a new record and apply the configuration. It's used to handle new records inside databases to mimic a table behavior.

The input should be a JSON esmith record.

Example: system-hosts.

read¶

Read the current system status and configuration. It should return an object with status and configuration fields.

JSON format:

{
  "status" : { ... }
  "configuration": { ...}
}

Example: system-openssh.

update¶

Update and existing record or a key inside the configuration database and apply the configuration.

Example: system-openssh.

delete¶

Delete and existing record and apply the configuration.

Example: system-hosts.

validate¶

Validate the given input. If validation fail, raise a validation error and exit 1. Otherwise return a success and exit 0.

execute¶

Execute a command in foreground or background. This type of operation can return raw output from underlying system.

Example: system-backup

hints¶

Execute system checks and propose configuration tweaks.

Check out the JSON format.

Documentation¶

When creating new helpers, remember to write the related documentation.

Download the template and edit it
Add the new document inside the docs/docs/api directory
Add the new document inside the navigation menu

Try to respect the following rules:

always use a correct header level
add examples to you documentation
enable syntax highlighting for code