Skip to content

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

Open
JesperSchulz wants to merge 2 commits into
mainfrom
jesperschulz-seed-web-services-knowledge-domain
Open

Seed web-services (API v2) knowledge domain#45
JesperSchulz wants to merge 2 commits into
mainfrom
jesperschulz-seed-web-services-knowledge-domain

Conversation

@JesperSchulz

@JesperSchulz JesperSchulz commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

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 5034050357 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-keyODataKeyFields = SystemId + field(id; Rec.SystemId) for stable addressing.
  3. expose-only-committed-data-from-api-readsRec.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-pagesInsertAllowed/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 seveneight; 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.

Jesper Schulz-Wedde and others added 2 commits June 24, 2026 12:38
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>
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