Methods¶

This page lists the methods the RPC server answers and how each one differs from running the same command on the command line.

The CLI Reference is the canonical description of what these commands do, what their options mean, and what the defaults are. This solely outlines the differences via RPC.

Parameter names¶

A method's parameters are its command's long options with hyphens replaced by underscores, so --skip-scan becomes skip_scan. Value types, defaults, and meanings are the same as on the command line.

Options that exist only to shape terminal output have no wire equivalent, and sending one is an error rather than a silently ignored field. The same applies to a misspelled name. See Parameters are named.

The global options are not method parameters. Those that apply at all are passed when the server starts; see fxv rpc.

Results¶

For a method that has a command line equivalent, result is the same output that command produces under --format json. See Output Formats.

A result is only present on success. A call that fails returns an error object and no result, rather than reporting the failure in its output the way the command line does. See Errors.

Method List¶

Methods that run a command:

• history - equivalent to fxv history.
• status - equivalent to fxv status.
• user - equivalent to fxv user.

Methods that manage the connection, which have no command line equivalent:

• ping - checks that the server is answering.
• server.info - reports the server's version and the methods it answers.
• shutdown - ends the connection.

history¶

Equivalent to fxv history.

Parameters: num, branch, published_only, draft_only.

status¶

Equivalent to fxv status.

Parameters: skip_scan, skip_remote_update.

Nothing else differs from the command line.

user¶

Equivalent to fxv user.

The subcommand becomes a required action parameter, one of "add", "edit", or "deactivate". That action's options are the rest of the parameters, and username is required for all three.

{"jsonrpc":"2.0","id":1,"method":"user","params":{"action":"add","username":"bot-builder","email":"[email protected]"}}

ping¶

Checks that the server is running and answering. Touches no workspace state, so it answers even when the workspace is in a state that other methods would fail on.

Parameters: None

Result: the string "pong".

{"jsonrpc":"2.0","id":1,"method":"ping"}

{"jsonrpc":"2.0","result":"pong","id":1}

server.info¶

Reports what this server is and what it answers. A client should call this once at startup and read methods, rather than discovering the method set by calling something and handling the failure.

Parameters: None

Result: an object with three fields.

• methods - the names of every method this server answers.
• protocol - the wire protocol identifier, currently jsonrpc-2.0-ndjson.
• version - the version of the fxv binary serving the connection.

{"jsonrpc":"2.0","id":1,"method":"server.info"}

{"jsonrpc":"2.0","result":{"methods":["status","history","user","ping","shutdown","server.info"],"protocol":"jsonrpc-2.0-ndjson","version":"0.6.0"},"id":1}

shutdown¶

Ends the connection. The server sends the response first, then stops reading, so a client that supplied an id always receives the acknowledgement before the stream closes.

Closing the server's standard input ends the connection as well. Call shutdown when you would like to confirm a clean shutdown.

Parameters: None

Result: the object {"ok": true}.

{"jsonrpc":"2.0","id":1,"method":"shutdown"}

{"jsonrpc":"2.0","result":{"ok":true},"id":1}

A shutdown the server rejects does not end the connection. See The connection lifecycle.