Concepts

References

References

GPALRestAPI: The REST Automation Server

A Standalone REST Server for Browser Automation

GPALRestAPI is a native Windows application that OttoMagic launches. It starts on a local port and exposes browser automation as HTTP endpoints. GPAL uses OttoMagicClient as its typed fluent wrapper, but the endpoints themselves are plain REST -- any language or tool that can make HTTP calls can drive the browser through GPALRestAPI.

// GPAL talks to GPALRestAPI through OttoMagicClient

GPAL.OttoMagicClient.GoTo("https://example.com").Execute();

var el = GPAL.OttoMagicClient.QuerySelector(".login-btn").Execute<GPALElement>();

GPAL.OttoMagicClient.LeftClick(el.ElementId).Execute();


// The same endpoints are callable from any HTTP client

// POST http://localhost:PORT/GoTo { "url": "https://example.com" }

// POST http://localhost:PORT/Query { "css": ".login-btn" }

NOTE

In GPAL workflows you rarely call GPALRestAPI directly -- OttoMagicClient provides a fluent typed interface over the endpoints. MagicHelper wraps the same surface as single-step methods.

Endpoint Categories

GPALRestAPI endpoints cover navigation, element interaction, element queries, script injection (before page load, not arbitrary execution during the workflow), storage operations across all browser storage types, page inspection, and DOM context switching. The full surface is accessible via OttoMagicClient in GPAL or from any HTTP client directly.

// Navigation

GPAL.OttoMagicClient.GoTo(url).Execute();

GPAL.OttoMagicClient.NewTab(url).Execute<TabTuple>();

GPAL.OttoMagicClient.Back().Execute();

// Element interaction

GPAL.OttoMagicClient.QuerySelector(".btn").Execute<GPALElement>();

GPAL.OttoMagicClient.LeftClick(elementId).Execute();

GPAL.OttoMagicClient.RightClick(elementId).Execute();

GPAL.OttoMagicClient.FillInOverwrite(elementId, text).Execute();

GPAL.OttoMagicClient.Hover(elementId).Execute();

// Storage and page inspection

GPAL.OttoMagicClient.GetCurrentUrl().Execute();

GPAL.OttoMagicClient.GetPageSource().Execute();

GPAL.OttoMagicClient.GetStorage(WebsiteStorageType.Cookie).Execute();

GPAL.OttoMagicClient.SetStorage(WebsiteStorageType.LocalStorage, key, val).Execute();

// Script injection and DOM context

GPAL.OttoMagicClient.InjectScript(initScript).Execute();

GPAL.OttoMagicClient.InIframe(frameId, innerEl).Execute();

GPAL.OttoMagicClient.InShadowdom(host, innerEl).Execute();

NOTE

GPALRestAPI includes a parallel set of persistent endpoints -- QueryPersistentSelector, EvaluatePersistent, and their multi-result variants. These are used by GPAL's persistent selector system to check for nag elements between units of work without disrupting the main DOM context.

Calling GPALRestAPI From Outside GPAL

Because GPALRestAPI is a standard HTTP server, any client that can make REST requests can reach it. GPALRestAPI scans for a free port starting at 3000 and, once bound, broadcasts the port number as a UTF-8 string to UDP 127.0.0.1:47623. GPAL receives this automatically and sets GPAL.OttoMagicRestApiBaseUrl. External code can do the same: open a UdpClient on port 47623 before OttoMagic launches, receive the broadcast, then address GPALRestAPI at the returned port for the duration of the session.

// Open the UDP listener BEFORE OttoMagic

// launches

using var udp = new UdpClient(47623);

udp.Client.ReceiveTimeout = 30_000; // 30-second timeout

var remoteEp = new IPEndPoint(IPAddress.Any, 0);

byte[] data = udp.Receive(ref remoteEp);

string port = Encoding.UTF8.GetString(data).Trim();


// GPALRestAPI is now reachable at this port for the session

string baseUrl = $"http://localhost:{port}/";

// POST {baseUrl}/GoTo { "url": "https://example.com" }

// POST {baseUrl}/Query { "css": ".login-btn" }

NOTE

GPAL listens for this broadcast once at startup -- if GPALRestAPI restarts and acquires a different port, the workflow must also restart to pick up the new address.

On this page

References
GPALRestAPI: The REST Automation Server
  • A Standalone REST Server for Browser Automation
  • Endpoint Categories
  • Calling GPALRestAPI From Outside GPAL
    • 💬 Ask GPAL