Why hand-written on Kiota?

Primary source: ADR 003 — Hand-written client on Kiota runtime abstractions.

The decision

The SDK is built directly on Microsoft's Kiota runtime abstractions (kiota-abstractions-go, kiota-http-go, the kiota-serialization-* packages) — but the request builders, models, and response envelopes are written by hand, not generated by the Kiota CLI from an OpenAPI description.

Why not generate?

• No authoritative OpenAPI specs. ServiceNow doesn't publish complete, accurate OpenAPI documents for its REST APIs. Generating from an incomplete spec produces an incomplete SDK; maintaining hand-written specs just to feed a generator moves the hand-work one step earlier without removing it.
• ServiceNow's response shapes need judgment. Envelopes (result wrapping), three-faceted fields (value / display value / link), and table-generic endpoints (/table/{tableName} serving every schema) don't map cleanly onto generator output. Hand-writing lets the SDK model these as first-class concepts (RecordElement, ServiceNowCollectionResponse[T]) instead of generated approximations.

Why still Kiota, then?

The runtime does real work that would otherwise be reinvented: URI-template expansion, authentication provider plumbing, serialization registries, middleware/retry handling, and backing stores. Building on it also keeps the SDK familiar: a developer coming from msgraph-sdk-go finds the same request-builder chaining, RequestConfiguration shapes, and model accessors here.

What this means for contributors

The consistency a generator would enforce mechanically, this repo enforces by convention — that's why the module pattern is strict:

• Follow the Add a new API module playbook exactly; the structural uniformity across *api packages is the hand-written substitute for generated code.
• Match Kiota idioms when in doubt: if msgraph-sdk-go does it a certain way, that's the default answer here too.