Concepts

Advanced Topics

Advanced Topics

OpenAPI Maps: Machine-Readable API Contracts

What Is an OpenAPI Specification

An OpenAPI specification (originally called Swagger) is a YAML or JSON document that describes a REST API in a format both humans and machines can read. Each operation records its HTTP method and path, which parameters are mandatory vs. optional, what the request body looks like, and what response shapes to expect. The format is an industry standard -- code generators, test runners, mock servers, and documentation tools all consume it directly.

# openapi.yaml -- excerpt showing one endpoint

paths:

/goto:

post:

summary: Navigate to a URL

requestBody:

required: true

content:

application/json:

schema:

required: [url]

properties:

url:

type: string

format: uri

/left-click:

post:

summary: Left-click an element

requestBody:

content:

application/json:

schema:

properties:

css: { type: string }

elementId: { type: string }

x-custom-validation: >-

At least one of css, elementId, or gpalElements must be present

LoadOpenAPIMap and Automatic Validation

LoadOpenAPIMap() is called once to configure the RESTClient instance -- it parses the spec, extracts the best server URL from the servers block, and builds a validation table keyed by HTTP method and path. After that single configuration call, you use normal fluent syntax to call endpoints repeatedly on the same client. A second RESTClient would be used for a different base URL -- each client holds its own map. Missing mandatory parameters emit a WARNING event through the GPAL event system so your log flags the gap without stopping the workflow.

// Configure once

var api = GPAL.RESTClient

.LoadOpenAPIMap("openapi.yaml")

.WithName("MyApiClient");


// Then call any endpoint repeatedly with normal fluent syntax

api.WithEndpoint("goto")

.WithParameters(new { url = "https://example.com" })

.Execute();


api.WithEndpoint("left-click")

.WithParameters(new { css = ".submit-btn" })

.Execute();


// A different API = a new RESTClient with its own map

var other = GPAL.RESTClient

.LoadOpenAPIMap("https://other.example.com/openapi.yaml");

NOTE

Validation logs WARNING events but never throws or aborts the call.

GPALRestAPI's Own Spec as a Worked Example

GPALRestAPI ships with an openapi.yaml placed next to its executable by the installer. The spec documents all browser automation endpoints -- navigation, element interaction, storage, scripting, and window management -- including each endpoint's mandatory fields, optional fields, and custom validation rules captured as x-custom-validation extensions. Passing this file to LoadOpenAPIMap() gives any GPAL.RESTClient full parameter validation for direct GPALRestAPI calls made outside of OttoMagicClient.

// Configure once from the spec placed next to GPALRestAPI.exe

string specPath = Path.Combine(

AppDomain.CurrentDomain.BaseDirectory, "openapi.yaml");


var restClient = GPAL.RESTClient

.LoadOpenAPIMap(specPath)

.WithName("DirectRestClient");


// Then use normal fluent syntax for every call

restClient.WithEndpoint("left-click")

.WithParameters(new { css = ".submit-btn" })

.Execute();


restClient.WithEndpoint("get-current-url")

.Execute<string>();

On this page

Advanced Topics
OpenAPI Maps: Machine-Readable API Contracts
  • What Is an OpenAPI Specification
  • LoadOpenAPIMap and Automatic Validation
  • GPALRestAPI's Own Spec as a Worked Example
    • 💬 Ask GPAL