agama-new-api.md

New HTTP API

The new API is designed around 3 main concepts: system, config and proposal.

• system: represents the current status of the running system.
• config: represents the configuration for installing the target system.
• proposal: represents what is going to be done in the target system.

The config contains elements that can modify the system, the proposal or both. For example, the dasd config changes the system, and the storage config changes the proposal. In other cases like network, the config can affect to both system and proposal.

API summary

GET             /system
GET             /config
GET             /config/{scope}
GET PUT PATCH   /config/user
GET PUT PATCH   /config/user/{scope}
GET POST        /questions
POST            /questions/answer
GET             /proposal
GET             /state
GET             /issues
POST            /action

GET /system

Returns a JSON with the info of the system (storage devices, network connections, current localization, etc).

Server actions

1. Probe the system if not probed yet (storage, network, locatlization, etc)

GET /config/full

Returns the full config JSON.

There is a distinction between full config and user config:

• The user config is the config explicity set by the user.
• The full config is the config used for calculating the proposal and it is built by merging the default config and the user config. The default config is built from the system info and the product info.

For example, if only the locale was configured by the user, then the user config has no keymap property. Nevertheless, the full config would have the keymap value from the default config.

If there is no config yet (i.e., product not selected), then it returns a 404 error code.

GET /config/user

Returns the user config JSON.

If there is no config yet (i.e., product not selected), then it returns a 404 error code.

PUT /config/user

Replaces the user config with the given config.

If the result is an invalid full config (e.g., without a product), then it returns an error (400 ?).

Server actions

1. Update the system (if needed)
2. Calculate the proposal

PATCH /config/user

Merges the user config with the given config.

If the result is an invalid full config (e.g., without a product), then it returns an error (400 ?).

Server actions

1. Update the system (if needed)
2. Calculate the proposal

PUT /config/user/{scope}

Replaces the scope of the user config with the given scope config.

If the result is an invalid full config (e.g., without a product), then it returns an error (400 ?).

Server actions

1. Update the system (if needed)
2. Calculate the proposal

POST /action

Allows performing actions that cannot be done as side effect of applying a config. For example, start the intallation, reload the system, etc. The actions schema defines the possible actions, parameters, etc.

NOTE: The actions schema is not defined yet.

Example: reload the system

In some cases, the clients need to request a system reload. For example, if you create a RAID device using the terminal, then you need to reaload the system in order to see the new device. In the future, reloading the system could be automatically done (e.g., by listening udisk dbus). For now, reloading has to be manually requested.

POST /action { "reloadSystem": { scope: "storage" } }

Example: change the system localization

Sometimes we need to directly modify the system without changing the config. For example, switching the locale of the running system (UI language).

POST /action { "configureL10n": { language: "es_ES" } }

Example: start installation

The installation can be started by calling the proper action.

POST /action "install"