Skip to main content

V2 Discrepancy Report (Docs vs Actual V2 Contract)

Scope​

This report compares:

  1. docs/api declared endpoint contracts (method + path + described payloads)
  2. Actual V2 OpenAPI + V2 controller/DTO implementation in services/amm/agent-web-api/src/api/v2/**

It highlights discrepancies that affect integration reliability and migration planning.

Executive Summary​

  • docs/api declared endpoints: 49
  • V2 OpenAPI endpoints: 34
  • Endpoints in docs but not in V2 OpenAPI: 13
  • Endpoints in V2 OpenAPI but not in docs: 3

The highest-risk mismatch is in the Apps domain (approval response payload), plus major missing/overstated coverage in Analytics Apps.

Findings​

1) Apps approval contract mismatch (response shape)​

What docs say​

  • POST /clients/{client_id}/apps/approvals
  • POST /clients/{client_id}/apps/approvals/remove
  • Response shape with succeeded[] and failed[]

Evidence:

  • docs/api/apps/approval.md:3
  • docs/api/apps/approval-remove.md:3
  • docs/api/apps/approval.md:35

What V2 actually exposes​

  • POST /clients/:client_id/apps/approvals
  • POST /clients/:client_id/apps/approvals/remove
  • Response shape: { requested_count, updated_count }

Evidence:

  • services/amm/agent-web-api/src/api/v2/apps/apps.controller.ts:277
  • services/amm/agent-web-api/src/api/v2/apps/apps.controller.ts:306
  • services/amm/agent-web-api/src/api/v2/apps/apps-dtos.ts:205

Impact​

Consumers built from docs will parse the wrong response payload fields.

2) Apps DTO model mismatch (docs describe a different object than V2 returns)​

What docs describe​

  • App includes embedded catalog_app
  • App includes license_count
  • PATCH /apps/{app_id} supports license_count

Evidence:

  • docs/api/apps/index.md:83
  • docs/api/apps/index.md:120
  • docs/api/apps/update.md:24

What V2 implementation defines​

  • AppDetailDto uses legacy fields like app_name, vendor, categories, web_urls
  • UpdateAppBodyDto only has is_favorite and is_approved
  • No license_count in v2 apps DTOs

Evidence:

  • services/amm/agent-web-api/src/api/v2/apps/apps-dtos.ts:139
  • services/amm/agent-web-api/src/api/v2/apps/apps-dtos.ts:80

Impact​

The documented Apps contract is not the currently shippable V2 contract.

3) App approval audit/history accepted in docs, still missing from V2 contract​

Observed gap​

V2 docs now include a proposed app history contract, but the V2 implementation/OpenAPI still does not expose it. Frontend workflows still depend on the V1 history endpoints.

Evidence (V1 exists):

  • services/amm/agent-web-api/src/api/v1/apps/apps.controller.ts:199
  • services/amm/agent-web-api/src/api/v1/apps/apps.controller.ts:243
  • services/amm/agent-web-api/src/api/v1/apps/apps.controller.ts:283

Evidence (frontend still using V1 history):

  • apps/amm-web/src/features/apps/hooks/useAppApprovalMutations.ts:108
  • apps/amm-web/src/features/apps/hooks/useAppHistoryComment.ts:42
  • apps/amm-web/src/features/apps/queries/app-queries.ts:208

Evidence (proposed V2 docs now exist):

  • docs/api/app-history-design-review.md
  • docs/api/apps/history.md
  • docs/api/apps/history-notes.md

Evidence (V2 OpenAPI/controller still has no history):

  • services/amm/agent-web-api/src/api/v2/apps/apps.controller.ts

Impact​

Migration to pure V2 still cannot fully support approval audit/comment workflows until the proposed history endpoints are implemented and added to the generated contract.

4) Analytics Apps coverage mismatch (documented endpoints not implemented in V2)​

Endpoints documented but missing from V2 OpenAPI​

  • /clients/{client_id}/analytics/apps/ai/users
  • /clients/{client_id}/analytics/apps/ai/users/summary
  • /clients/{client_id}/analytics/apps/ai/recent
  • /clients/{client_id}/analytics/apps/ai/recent/summary
  • /clients/{client_id}/analytics/apps/ai/departments
  • /clients/{client_id}/analytics/apps/ai/departments/summary
  • /clients/{client_id}/analytics/apps/utilization/timeseries
  • /clients/{client_id}/analytics/apps/utilization/categories
  • /clients/{client_id}/analytics/apps/utilization/users
  • /clients/{client_id}/analytics/apps/utilization/departments

Evidence (docs claim/describe):

  • docs/api/analytics/index.md:44
  • docs/api/analytics/index.md:55
  • docs/api/app-usage-dashboard-spec.md:28
  • docs/api/app-usage-dashboard-spec.md:39

Evidence (actual V2 controller routes):

  • services/amm/agent-web-api/src/api/v2/analytics-apps/app-activity/app-activity.controller.ts:61
  • services/amm/agent-web-api/src/api/v2/analytics-apps/app-utilization/app-utilization.controller.ts:80
  • services/amm/agent-web-api/src/api/v2/analytics-apps/app-utilization/app-utilization.controller.ts:195
  • services/amm/agent-web-api/src/api/v2/analytics-apps/app-utilization/app-utilization.controller.ts:261

Impact​

Docs currently overstate available V2 analytics functionality.

5) AI analytics docs must consistently treat the full AI family as deprecated/removal-only​

Current direction​

All six AI analytics endpoints are deprecated and being removed. The replacement surface is the generic analytics utilization family with AI category filters.

Evidence:

  • docs/api/analytics/apps-ai-overview.md:8
  • docs/api/app-usage-dashboard-spec.md:507
  • docs/api/analytics/index.md:51

Impact​

Any overview or migration note that implies partial AI endpoint support will send consumers toward routes that should be retired instead of migrated away from.

6) Internal contradiction: approved/new vs proposed/future in analytics index​

Contradiction​

The same analytics overview marks some utilization subroutes as approved/new and later lists them as proposed/future.

Evidence:

  • docs/api/analytics/index.md:44
  • docs/api/analytics/index.md:176

Impact​

Team cannot infer implementation status from docs with confidence.

7) Catalog app path parameter naming mismatch​

What docs use​

  • /catalog-apps/{catalog_app_id}
  • /catalog-apps/{catalog_app_id}/desktop-aliases
  • /catalog-apps/{catalog_app_id}/url-patterns

Evidence:

  • docs/api/catalog-apps/details.md:3
  • docs/api/catalog-apps/desktop-aliases.md:3
  • docs/api/catalog-apps/url-patterns.md:3

What V2 OpenAPI uses​

  • /catalog-apps/{id}
  • /catalog-apps/{id}/desktop-aliases
  • /catalog-apps/{id}/url-patterns

Evidence:

  • apps/amm-web/src/api/generated/v2-dtos.ts:13

Impact​

Path parameter naming divergence can break generated clients and copy-pasted examples.

8) “Generated validators” reference needs regeneration discipline​

Docs claim​

nestjs-class-validators.md is the generated implementation reference for all request/response shapes.

Evidence:

  • docs/api/index.md:38

Current status​

The app approval route naming is now aligned in validators and docs:

  • POST /apps/approvals
  • POST /apps/approvals/remove

Evidence:

  • docs/api/nestjs-class-validators.md:693
  • services/amm/agent-web-api/src/api/v2/apps/apps.controller.ts:277

Impact​

Without consistent regeneration, this reference can drift again and lose source-of-truth value.

Endpoint-Level Diff (V2 Normalized)​

In docs, missing from V2 OpenAPI​

  • /catalog-apps/{catalog_app_id}
  • /catalog-apps/{catalog_app_id}/desktop-aliases
  • /catalog-apps/{catalog_app_id}/url-patterns
  • /clients/{client_id}/analytics/apps/ai/departments
  • /clients/{client_id}/analytics/apps/ai/departments/summary
  • /clients/{client_id}/analytics/apps/ai/recent
  • /clients/{client_id}/analytics/apps/ai/recent/summary
  • /clients/{client_id}/analytics/apps/ai/users
  • /clients/{client_id}/analytics/apps/ai/users/summary
  • /clients/{client_id}/analytics/apps/utilization/categories
  • /clients/{client_id}/analytics/apps/utilization/departments
  • /clients/{client_id}/analytics/apps/utilization/timeseries
  • /clients/{client_id}/analytics/apps/utilization/users

In V2 OpenAPI, missing from docs​

  • /catalog-apps/{id}
  • /catalog-apps/{id}/desktop-aliases
  • /catalog-apps/{id}/url-patterns

Risk Ranking​

High​

  • Apps approval response-shape mismatch
  • Apps DTO mismatch (catalog_app/license_count vs actual v2 shape)
  • Missing app history/audit trail implementation for v2 migration
  • Analytics endpoint availability mismatch

Medium​

  • AI endpoint removal messaging must stay consistent
  • Approved/new vs proposed/future contradictions
  • Catalog path parameter naming mismatch

Low​

  • Potential future staleness of generated validators reference
  1. Lock canonical V2 truth source (OpenAPI generated from code) and align Apps docs first.
  2. Implement the proposed app history endpoints and add contract coverage.
  3. Align analytics docs to actual implemented endpoints, or implement missing routes and regenerate OpenAPI.
  4. Resolve catalog {catalog_app_id} vs {id} naming consistency.
  5. Keep nestjs-class-validators.md generation/output in sync with contract changes.

Notes​

  • This report focuses on V2 discrepancy only (as requested), not full V1 parity gap analysis.
  • Evidence pointers are file+line references from current repository state.