Why does Appium send its mobile: commands through execute/sync instead of new endpoints?

## The constraint that shapes the design A **W3C WebDriver** remote end serves a defined set of routes. A client library knows those routes because they are written in the specification; it cannot know a route the specification does not describe. Appium, meanwhile, needs to expose hundreds of platform-specific commands — installing a build of the curling-club ladder app, backgrounding it, clearing its stored data, flinging a long standings list, reading device state. Declaring a new HTTP route for each one would leave every command unreachable from an unmodified WebDriver client and would quietly turn Appium into a protocol of its own. So Appium does not add routes for them. It reuses one standard route as a named command channel, and the whole extension surface travels through that single hole in the protocol. ## How the channel works `POST /session/:sessionId/execute/sync` is an ordinary W3C route. In a browser it takes a `script` string of JavaScript and an `args` array of values to pass to it. Appium keeps the request shape and changes what the two members mean: - `script` carries the **name of a driver command**, written with a namespace prefix — `mobile:` on the native drivers, `flutter:` on the official Flutter driver. - `args` carries **exactly one object**, whose members are the command's named parameters. Not a positional list — one map, even when the command takes nothing and the map is empty. - The response comes back in the ordinary W3C envelope, so a client parses it exactly as it parses a find or an attribute read. Because the route is standard, any WebDriver client can reach any driver's extension commands with no new protocol code. A language binding's convenience helper for a `mobile:` command is a wrapper over this same call, not a different mechanism. ## The names belong to drivers, not to Appium This is the half that costs people a debugging session. There is no Appium-wide `mobile:` vocabulary. Each driver declares its own **execute-method map**, and the server dispatches an `execute/sync` call by looking the `script` string up in the map of the driver that owns the session. Two consequences: - The same intent has different names on different drivers. To fling the curling-club ladder standings, the UiAutomator2 driver on Android answers `mobile: swipeGesture`; the XCUITest driver on Apple platforms answers `mobile: swipe`. Writing "UiAutomator2's `mobile: swipe`" reads plausibly and is simply false. - A driver inherits the map of the driver it extends, so a command can be answerable without being declared by the driver you named in the session. A name is therefore only meaningful together with its driver. "Which `mobile:` command backgrounds an app?" is not a well-formed question until you say which driver is running. ## What the design buys, and what it costs - **Buys:** no protocol fork, so an unmodified W3C client works against every driver. - **Buys:** a driver can add commands on its own release schedule without touching the server's route table. - **Buys:** the extension surface is self-describing per driver — the map is the list of what that driver can do. - **Costs:** a wrong or unavailable name is a **run-time** failure. Nothing about `execute/sync` is checked when the session is created, so a curling-club ladder test that posts an unsupported name starts cleanly and dies at the step. - **Costs:** parameters are per command, so the other platform's equivalent usually takes a differently shaped map. - **Costs:** the surface moves with the driver rather than with the specification, so a driver upgrade is exactly where an execute method can change under you. ## The three failure shapes worth recognising 1. **Right shape, wrong driver.** The request is well formed but the name is not in this driver's map — usually a command borrowed from the other platform's driver. 2. **Right name, wrong map.** The command exists, but the parameter object is missing a member or uses another driver's spelling for it. 3. **A name that never existed.** Documentation is not the contract. The XCUITest driver's own reference prints `mobile: availableConditionInducer`, a name that appears nowhere in its source; the real command is `mobile: listConditionInducers`. Verify a name against the driver's execute-method map before depending on it. ## The shape to remember One standard endpoint, one string that names a driver command, one object of parameters. The endpoint is deliberately unremarkable — it is inherited, it is boring, and it never changes — while the name is everything, because the name is where Appium's per-driver, per-platform surface actually lives.