Multiplexer (Mux) Endpoint#

The multiplexer (mux) endpoint is a single endpoint that can perform multiple related actions with one call. Where GET /node/UID12345 retrieves a single node’s detailed data, a single POST /mux call, with proper parameters, can return the detailed data for all nodes in the cluster or for a specific subset of nodes.

Since the mux endpoint can perform any operation, the call is always made as a POST call with parameters indicating what the underlying request(s) should be interpreted as.

Input Parameters#

Input parameters include:

url
     The templatized URL for the underlying, requested action(s).

url_fields
     The set of arguments to be used to select which objects to take action
     on. Often this is a set of UIDs or a wildcard. A separate action is
     taken for each item in url_fields.

method
     The HTTP-type of action to take on each URL(GET, POST, PUT, DELETE)

params
     The set of arguments to send as query parameters into the underlying action(s)

content
     The data to send as content into the underlying action(s)

Example#

When running cw-nodectl ls -l, the client actually makes a call to the mux endpoint:

POST /api/v1/mux
   query parameters:  log=GET-/node/UID
   json-data:  {
      “url": "/node/{uid}”,
      “method”: “GET”,
      “content”: None,
      “params”: {},
      “url_fields”: {“*”: {“uid”: None} }
   }

Note

The query parameters given to the overall /mux call (log=GET-/node/UID) are a convenience for logging the method of request being made. The parameters can be omitted if desired.

The posted json-data indicates the details of the actual request(s).

  • url: “/node/{uid}”: Asks the mux endpoint for information related to /node/{uid} where “{uid}” is defined later.

  • url_fields: “*”: { “uid”: null }: Tells the mux endpoint which items to expand in the url, or alternatively which items to select for taking the action. The mux endpoint then calls the url endpoint multiple times - once for each node-UID found in url_fields. Since this is a wildcard (“*”) all available entries for the URL (/node/{uid}) are queried and returned.

  • method: In this example, we are asking for a GET method to read the detailed data about the node (as defined by the /node/{uid} endpoint).

  • content: No additional content is needed for this GET operation.

  • params: No additional query parameters are needed for this GET operation.

Since the URL given is for detailed information, /node/{uid}, and not a simple listing of available UIDs, the mux endpoint returns the detailed information for all nodes in a single API call. This greatly reduces the number of network requests needed because, instead of making 10s or 100s of calls to GET /node/UID1, GET /node/UID2, etc., the client makes one call to POST /mux and retrieves all of that data at once.

To request a set of UIDs rather than all UIDs, use:

url_fields: {  “<UID1>”:{“uid”:null}, “<UID2>”:{“uid”:null} }

The “UID” can be any unique, matchable field for the primitive type. For example, nodes can be matched on UID, node name, MAC address, or IP-address. Images can be matched on UID or image name.

Other Parameters#

Note

These parameters may be applicable for other endpoints.

content
    If the action being requested requires more data, then it can be
    included in the “content” field. For “create” actions, this includes the
    data required by the new object. For executing a command on a node, this
    includes the command to execute and any inputs needed by that command.

stdin
    Used to send standard-input data (as if the data were typed in on a
    keyboard). This data is expected to be encoded using the
    "stdin_encoding" method below.

stdin_encoding
    When sending stdin data, you must define the format of the data.
    Currently, only “null” (raw text) and base64 data are supported.