Skip to content

Seed web-services (API v2) knowledge domain - #45

Merged
Jesper Schulz-Wedde (JesperSchulz) merged 2 commits into
mainfrom
jesperschulz-seed-web-services-knowledge-domain
Jun 25, 2026
Merged

Jesper Schulz-Wedde (JesperSchulz) merged 2 commits into
mainfrom
jesperschulz-seed-web-services-knowledge-domain

Conversation

@JesperSchulz

@JesperSchulz Jesper Schulz-Wedde (JesperSchulz) commented Jun 24, 2026 •

Copy link
Copy Markdown
Contributor

Seeds a new web-services knowledge domain covering API endpoint design and behavior (API v2 / API pages), plus a matching review leaf skill and the routine wiring.

Scope / de-duplication

This domain deliberately covers API endpoint design and behavior only. It excludes topics already owned by other domains, to avoid duplication:

  • API entity naming, camelCase properties, DelayedInsert, and the vX.Y version-string format are owned by the style domain.
  • The ReadIsolation-vs-LockTable mechanic (lock blast-radius / read performance) is owned by the performance domain. The committed-data article here is framed strictly as the endpoint's data-consistency contract (what a consumer receives), not as a locking/performance concern.

Knowledge articles (6)

Each is a .md with sibling .good.al / .bad.al samples, domain: web-services, unique object IDs in the 50340–50357 range (gaps at 50342/50343/50346/50347 left from the trimmed articles; no renumbering, no collisions):

  1. set-required-api-page-properties — a PageType = API page must declare APIPublisher, APIGroup, APIVersion, EntityName, EntitySetName, and SourceTable.
  2. expose-systemid-as-the-api-key — ODataKeyFields = SystemId + field(id; Rec.SystemId) for stable addressing.
  3. expose-only-committed-data-from-api-reads — Rec.ReadIsolation := IsolationLevel::ReadCommitted in OnOpenPage so the endpoint returns only committed data (bc-version [22..]).
  4. expose-operations-as-bound-actions — [ServiceEnabled] bound actions via WebServiceActionContext, not side-effecting status flags.
  5. version-apis-by-adding-not-mutating-published-versions — add a new APIVersion alongside the published one instead of mutating it in place.
  6. disable-write-operations-on-read-only-api-pages — InsertAllowed/ModifyAllowed/DeleteAllowed = false (and Editable = false).

New leaf skill

  • microsoft/skills/review/al-web-services-review.md — modeled on al-error-handling-review.md, sourced from domain: web-services knowledge.

Wiring

  • microsoft/skills/review/al-code-review.md — added the leaf to sub-skills, to the ## Source list, and to the line-6 description parenthetical (, web services).
  • README.md — leaf count seven → eight; appended , web services to the domain list.

Validation

  • python .github/scripts/validate_frontmatter.py → 0 errors / 0 warnings.
  • pwsh -File .github/scripts/Test-KnowledgeIndex.ps1 → PASSED (166 articles, deterministic, full coverage, selection inputs intact, no object-ID collisions). The knowledge index is generated, not committed.

Note on wiring conflicts

A routine wiring conflict is expected with other open leaf-domain PRs (#42 / #43 / #44) in al-code-review.md and README.md. Resolution: keep ALL leaves, and set the README leaf count = base + number of merged leaf domains.

Part of #34.

@JesperSchulz
Jesper Schulz-Wedde (JesperSchulz) force-pushed the jesperschulz-seed-web-services-knowledge-domain branch from 09a5bf2 to e310ad2 Compare June 25, 2026 10:30
Jesper Schulz-Wedde and others added 2 commits June 25, 2026 12:35
Add eight web-services API page knowledge articles (each with .good.al/.bad.al samples), a new al-web-services-review leaf skill, and wire it into al-code-review and the README.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Drop API entity-naming/camelCase and DelayedInsert articles (owned by the style domain). Reframe the committed-data and API-versioning articles to stay strictly within the endpoint design/behavior lane, and update the leaf skill's worklist tokens and Output example accordingly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@JesperSchulz
Jesper Schulz-Wedde (JesperSchulz) force-pushed the jesperschulz-seed-web-services-knowledge-domain branch from e310ad2 to 94c371d Compare June 25, 2026 10:36
@JesperSchulz
Jesper Schulz-Wedde (JesperSchulz) merged commit 13f47f6 into main Jun 25, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant