API Introspection

API Builder describes its generated surface through a standard OpenAPI 3.0 document. Because every endpoint is emitted as a real ASP.NET Core controller action (decorated with [HttpGet]/[HttpPost], [Route], [ProducesResponseType], and [FromQuery]/[FromBody] bindings), the ASP.NET Core API Explorer can reflect over it and produce a complete machine-readable schema. This enables:

• Auto-generation of API clients
• Dynamic form building based on schemas
• Validation rule discovery
• Documentation generation

note

There is no custom /api/schema family of endpoints. Schema discovery is done entirely through the OpenAPI document (served by Swagger in a host that wires it up) and, at runtime, a single engine diagnostics endpoint at GET /health that reports the loaded API version, modules, and compiler logs.

The OpenAPI Document

When the runtime host enables Swagger (see Runtime), the specification is served at:

GET /swagger/{version}/swagger.json     # OpenAPI 3.0 document
GET /swagger                            # Swagger UI

The document is generated by Swashbuckle from the runtime-generated controllers, so it always matches the endpoints the engine actually exposes for the resolved API version. You can also export the same OpenAPI 3.0 specification from the designer — see API Structure → Export.

Engine Health & Metadata

The runtime exposes an engine diagnostics endpoint that returns the currently loaded configuration:

Request:

GET /health

Response (200 OK):

{
  "projectName": "CustomerPortal",
  "apiName": "CustomerPortalAPI",
  "version": "1.0",
  "health": {
    "status": "Healthy",
    "message": "..."
  },
  "metadata": {
    "schemaVersion": "...",
    "modules": [ ... ],
    "logs": [ ... ]
  },
  "compiler": {
    "exception": null,
    "logs": [ ... ]
  }
}

When the host runs in multi-version mode, the response instead lists the available versions and the default version.

Use Cases

Dynamic Form Generation

UI applications can read the OpenAPI request/response schemas to generate forms automatically. Each operation's request body schema describes the fields, types, and validation constraints for the entity action:

// Fetch the OpenAPI document
const spec = await (await fetch('/swagger/v1/swagger.json')).json();

// Inspect the request body schema for a create endpoint
const createSchema = spec.paths['/sales/account/create'].post
  .requestBody.content['application/json'].schema;

Object.entries(createSchema.properties).forEach(([name, def]) => {
  createFormField({
    name,
    type: def.type,
    required: createSchema.required?.includes(name),
    maxLength: def.maxLength
  });
});

Client SDK Generation

The OpenAPI 3.0 document can drive standard client generators (openapi-generator, NSwag, Kiota) to produce typed clients:

// Generated from the OpenAPI schema
interface Account {
  id: string;
  name: string;
  telephone1?: string;
  emailAddress1?: string;
  accountCategoryCode?: number;
}

class AccountsApi {
  async create(account: Omit<Account, 'id'>): Promise<{ id: string }> {
    // POST /sales/account/create
  }

  async update(id: string, account: Partial<Account>): Promise<void> {
    // PUT /sales/account/{id}/update
  }
}

Validation

Because the schema carries type and length constraints (for example maxLength on string attributes), clients can validate inputs before submitting:

function validate(data, schema) {
  const errors = [];

  Object.entries(schema.properties).forEach(([name, def]) => {
    if (schema.required?.includes(name) && !data[name]) {
      errors.push(`${name} is required`);
    }
    if (def.maxLength && data[name]?.length > def.maxLength) {
      errors.push(`${name} exceeds maximum length of ${def.maxLength}`);
    }
  });

  return errors;
}