[ADMINAPI-1427] PRD: ODS Admin API 2.3 by stephenfuqua · Pull Request #393 · Ed-Fi-Alliance-OSS/ODS-Admin-API

stephenfuqua · 2026-07-14T02:57:25Z

Reverse-engineered product requirements document (PRD) for ODS Admin API version 2.3
Cleanup old documentation related to the cancelled Admin Console project

stephenfuqua · 2026-07-17T15:51:25Z

@@ -33,79 +33,9 @@ This guide will walk you through the steps to add three scopes (edfi_admin_api/f
   * **Description**: (Optional) Provide a description for the scope.
 3. Click the `Save` button to create the scope `edfi_admin_api/full_access`.

-#### Step 5: Create Scope edfi_admin_api/tenant_access


We backed out the Admin Console specific changes that introduced additional scopes.

stephenfuqua · 2026-07-17T15:52:39Z

I removed Open API specs that we don't need to keep in the repository any longer.

Copilot

Pull request overview

This PR adds a reverse-engineered Product Requirements Document (PRD) for ODS Admin API 2.3 and removes a large set of legacy/cancelled “Admin Console” design and generated OpenAPI documentation artifacts to reduce confusion and keep the docs aligned with the current product direction.

Changes:

Added a comprehensive PRD for ODS Admin API 2.3 (functional + non-functional requirements, personas/JTBD, architecture notes).
Removed Admin Console/worker removal docs, design docs, and generated OpenAPI files that are no longer relevant.
Small documentation + editor configuration tweaks (auth docs wording, markdown lint UL style rule).

Reviewed changes

Copilot reviewed 21 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/PRD-ODS-Admin-API-2.3.md	Adds a PRD describing Admin API/Management API behavior and requirements for 2.3.
docs/Instance-Worker-Removal.md	Removes legacy documentation for cancelled instance worker endpoint removal work.
docs/Healthcheck-Worker-Removal.md	Removes legacy documentation for cancelled healthcheck worker endpoint removal work.
docs/design/Integrate-Instance-Management.md	Removes Admin Console/worker integration design doc (Quartz-based).
docs/design/INTEGRATE-HEALTHCHECK-SERVICE.md	Removes Admin Console healthcheck service integration design doc.
docs/design/auth/README.md	Updates auth design narrative to reflect current Admin App/IdP direction.
docs/design/auth/KEYCLOAK.md	Updates Keycloak instructions to reflect the current single-scope model.
docs/design/adminconsole/WORKER-CRON-PROCEES.md	Removes Admin Console worker cron-in-container design doc.
docs/design/adminconsole/TENANT-DATA.md	Removes Admin Console tenant API design doc.
docs/design/adminconsole/SQL-SERVER-SUPPORT.md	Removes Admin Console instance-management SQL Server support design doc.
docs/design/adminconsole/readme.md	Removes Admin Console overall architecture/design entrypoint doc.
docs/design/adminconsole/notes.md	Removes Admin Console notes/persistence/auth brainstorming doc.
docs/design/adminconsole/INSTANCE-DATA.md	Removes Admin Console instance/worker endpoint and data model design doc.
docs/design/adminconsole/HEALTH-CHECK-WORKER.md	Removes Admin Console health check worker design doc.
docs/design/adminconsole/developer.md	Removes Admin Console EF migration/developer instructions doc.
docs/design/adminconsole/APIS-FOR-ADMIN-CONSOLE.md	Removes Admin Console endpoint catalog and system context doc.
docs/design/adminconsole/admin-api-adminconsole-2.3.yaml	Removes generated/curated Admin Console OpenAPI YAML artifact.
docs/design/adminconsole/admin-api-adminconsole-2.3-summary.md	Removes generated Admin Console OpenAPI summary markdown.
docs/design/ADMINAPI-1284-adminconsole-definition-removal.md	Removes analysis/design doc for Admin Console definition removal.
docs/api-specifications/openapi-yaml/admin-api-console-2.3.0-pre.yaml	Removes pre-release Admin Console OpenAPI spec artifact.
docs/api-specifications/openapi-yaml/admin-api-2.3.0-pre.yaml	Removes pre-release Admin API OpenAPI spec artifact.
.vscode/settings.json	Adjusts markdownlint unordered-list style rule to “consistent”.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Adopt persona definitions and shared job-to-be-done language from the approved Admin App v4.0 PRD (Platform host sysadmin, Operator, Vendor Application Administrator) for consistency across the two products, while keeping Admin API-specific personas and jobs distinct. Clarifies existing requirements (e.g. claim set transfer, ODS instance scope, credential distribution boundary) without adding new functionality.

…ented ones Verified each SHOULD-worded requirement against current source. Requirements with confirmed implementations (Swagger versioning, self-contained auth, query sorting/filtering, 409 conflicts, Docker/IIS migration guides, prod Swagger/registration gating, structured error logs, tenant caching, HTTP examples) are now SHALL. Removed NFR-SEC-9 (no rate limiting exists on /connect/register or /connect/token) and NFR-OBS-6 (no APM/tracing integration exists, and the entry only described an absence rather than a testable requirement). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…port

stephenfuqua · 2026-07-17T18:41:21Z

Reviewing docs/PRD-ODS-Admin-API-2.3.md for solution-leaning content (this is a requirements doc — should describe what/why, not how):

Section 5, "System architecture" (lines 399-413) — the biggest lean-into-solution. The table lists actual source file names (Program.cs, WebApplicationBuilderExtensions.cs, AdminApiDbContext.cs, TenantIdentificationMiddleware.cs, RequestLoggingMiddleware.cs, etc.). That's an implementation map, not a requirement — better suited to docs/developer.md or an architecture doc than a PRD.

Specific FR/NFR lines that prescribe a solution rather than a capability:

NFR-OBS-1: "The application SHALL use log4net for application logging." Naming a specific library is a solution choice. The actual requirement is the capability (structured, correlatable logging), already covered by NFR-OBS-2 through NFR-OBS-4.
NFR-OBS-2: "Request logging SHALL run before routing, authentication, and endpoint execution." Describes ASP.NET Core middleware pipeline ordering — a "how." The underlying "why" is likely "requests must be logged even when they fail before reaching an endpoint (e.g., 401/404)" — that's the requirement worth stating.
NFR-REL-7: "...use a distinct schema (i.e. adminapi)..." Borderline — schema isolation is a legitimate requirement (avoid colliding with ODS/API-owned objects across upgrades), but naming the literal schema string is implementation detail.
FR-AUTH-9 / NFR-COMPAT-5: "self-contained authentication" — really means "OpenIddict-based built-in token server." Could instead state the capability: "SHALL support built-in authentication without requiring an external identity provider," leaving OpenIddict as an implementation detail elsewhere.

Judgment calls left as-is — these read as "how" but are really public contract that a Management API requirements doc legitimately needs to pin down: POST /connect/token, POST /connect/register, the /v2/* route prefix, and the tenant header.

Review by Claude Code + Sonnet 5

…requirements

stephenfuqua · 2026-07-17T21:04:02Z

Reviewing docs/PRD-ODS-Admin-API-2.3.md for solution-leaning content (this is a requirements doc — should describe what/why, not how):

I have addressed all of these review comments.

stephenfuqua · 2026-07-17T21:39:58Z

The E2E tests were passing earlier. There is a single test failing, related to creating an Application. Since I haven't changed any source code - only documentation - this is rather strange, and it seems to be a flaky test.

Co-authored-by: stephenfuqua <9324390+stephenfuqua@users.noreply.github.com>

NFR-SEC-2 named the wrong OAuth scope (admin_api/full_access instead of edfi_admin_api/full_access). NFR-SDLC-2 now clarifies that 100% unit test coverage is the objective, not the 2.3 release's actual state. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

stephenfuqua changed the title ~~Draft PRD: ODS Admin API 2.3~~ [ADMINAPI-1427] PRD: ODS Admin API 2.3 Jul 17, 2026

stephenfuqua requested a review from Copilot July 17, 2026 15:50

Copilot started reviewing on behalf of stephenfuqua July 17, 2026 15:51 View session

stephenfuqua commented Jul 17, 2026

View reviewed changes

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread docs/PRD-ODS-Admin-API-2.3.md Outdated

Comment thread docs/PRD-ODS-Admin-API-2.3.md Outdated

Comment thread docs/design/auth/KEYCLOAK.md Outdated

Comment thread docs/design/auth/README.md Outdated

stephenfuqua and others added 8 commits July 17, 2026 12:00

maint: Relax the markdown rule on unordered lists

5f273af

docs: Add first draft PRD for ODS Admin API 2.3

a990d56

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs: Manual editing

4f0b175

docs: No need to carry these documents into the future

e2dccaf

docs: Remove leftover documentation for cancelled "Admin Console" sup…

ec9bbb0

…port

docs: Address all GHCopilot review comments

eb45849

stephenfuqua force-pushed the PRD branch from b37e6fc to eb45849 Compare July 17, 2026 17:01

stephenfuqua marked this pull request as ready for review July 17, 2026 18:09

docs: Reduce or explain implementation details that have leaked into …

d8b8f7e

…requirements

Copilot started work on behalf of stephenfuqua July 17, 2026 21:50 View session

Fix multitenant tenant cleanup to accept 204 deletes

1fc1a08

Co-authored-by: stephenfuqua <9324390+stephenfuqua@users.noreply.github.com>

Copilot finished work on behalf of stephenfuqua July 17, 2026 21:53

docs: Simplify the personas

115b62c

stephenfuqua mentioned this pull request Jul 19, 2026

[ADMINAPI-1428] PRD for ODS Admin API 2.4 #401

Draft

DavidJGapCR approved these changes Jul 28, 2026

View reviewed changes

DavidJGapCR merged commit b63d685 into main Jul 28, 2026
21 checks passed

DavidJGapCR deleted the PRD branch July 28, 2026 21:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[ADMINAPI-1427] PRD: ODS Admin API 2.3 - #393

[ADMINAPI-1427] PRD: ODS Admin API 2.3#393
DavidJGapCR merged 12 commits into
mainfrom
PRD

stephenfuqua commented Jul 14, 2026 •

edited

Loading

Uh oh!

stephenfuqua Jul 17, 2026

Uh oh!

stephenfuqua Jul 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stephenfuqua commented Jul 17, 2026 •

edited

Loading

Uh oh!

stephenfuqua commented Jul 17, 2026

Uh oh!

stephenfuqua commented Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

stephenfuqua commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stephenfuqua Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

stephenfuqua Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stephenfuqua commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stephenfuqua commented Jul 17, 2026

Uh oh!

stephenfuqua commented Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

stephenfuqua commented Jul 14, 2026 •

edited

Loading

stephenfuqua commented Jul 17, 2026 •

edited

Loading