REST schema items

The rest: realm brings explicitly declared HTTP properties and commands into the Schema. A REST service sets the connection and path boundary; its children describe the values Pinman can read or write and the actions a Profile can invoke.

Pinman usually tracks configuration on a particular machine, so REST is especially useful for services running on that machine. Pinman's audio, input, and overlay services, for example, expose settings through REST APIs. A Schema can also bring external-service data into Captures when it contributes to the machine's operating context, such as network status, weather conditions, or another environmental input.

REST declarations use the same locations, inheritance, and property metadata as other Schema Items. See Schema items for that shared model and Schema property fields for datatypes, I/O modes, formats, and UI controls.

Service structure#

This example reads and writes an audio service's volume property:

items:
  - itemtype: rest_root
    label: Services
    items:
      - selector: audio
        itemtype: rest_service
        service: api
        path_prefix: /api/controls
        items:
          - selector: volume
            itemtype: rest_property
            datatype: float
            read:
              path: /api/controls
              pointer: payload.volume_level
            write:
              method: POST
              path: /api/controls/volume
              pointer: volume

The resulting property belongs to the audio service beneath the rest: realm. Its read block extracts payload.volume_level from the response, while its write block sends the new value as volume.

rest_service#

Field	Required	Meaning
path_prefix	Yes	Path subtree that contains every declared operation.
service	No	Configured Pinman service slug; defaults to api.
base_url	No	Explicit endpoint for a third-party service.

service selects a connection already configured in Pinman. base_url supplies a fixed endpoint instead. In either case, path_prefix bounds every declared read, write, and command path.

rest_property#

A REST property represents state. Its read and write blocks are separate because a service may return several properties from one endpoint and accept updates at another.

Block	Fields
read	HTTP path and response pointer.
write	HTTP method, path, and request pointer.

Properties with the same write method and path form one composite resource. Before writing one property, Pinman reads the other declared fields and sends a combined request that preserves their values.

A connection failure gives the property an unreadable state. REST values are read live, so Backup has no file content to retain for them.

rest_command#

A REST command represents an action rather than a value. A Profile invokes the action through its invoke block; Captures and comparisons continue to describe the service properties that hold state.

This command sends a request to restart the service:

- selector: restart
  itemtype: rest_command
  label: Restart service
  invoke:
    method: POST
    path: /api/controls/restart

The command has no stored value. It runs only when a Profile explicitly invokes it.

Itemtypes#

Itemtype	Children	Purpose
rest_root	rest_service	Root of the REST realm.
rest_service	properties, commands	Connection and path boundary.
rest_property	none	Readable and optionally writable service value.
rest_command	none	Action invoked explicitly by a Profile.