Skip to main content

Catalog V2 OpenAPI Drift Report

Summary​

This report compares the documented v2 catalog API against the generated OpenAPI contract in services/amm/agent-web-api/openapi.json.

For this report, docs/api is the source of truth.

Scope Reviewed​

  • /v2/catalog-apps in services/amm/agent-web-api/openapi.json#L4329
  • /v2/catalog-apps/summary in services/amm/agent-web-api/openapi.json#L4462
  • /v2/catalog-apps/{id} in services/amm/agent-web-api/openapi.json#L4508
  • /v2/catalog-apps/{id}/url-patterns in services/amm/agent-web-api/openapi.json#L4573
  • /v2/catalog-apps/{id}/desktop-aliases in services/amm/agent-web-api/openapi.json#L4667
  • /v2/catalog-vendors in services/amm/agent-web-api/openapi.json#L4233
  • /v2/catalog-categories in services/amm/agent-web-api/openapi.json#L4125

Findings​

1. catalog-apps DTO shape does not match the docs​

The docs define the catalog-apps list response as CatalogApp[]. That means list and detail must both follow the CatalogApp DTO. The docs define CatalogApp.vendor as an embedded vendor object and categories as embedded category objects, and they document created_at and updated_at on the catalog app response:

The generated schemas in OpenAPI do not reflect that shape:

  • CatalogAppListItemDto in services/amm/agent-web-api/openapi.json#L12937
  • CatalogAppDetailDto in services/amm/agent-web-api/openapi.json#L13080

Documented shape​

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "canonical_name": "Google Chrome",
  "description": "A cross-platform web browser developed by Google",
  "display_colour": "#4285F4",
  "logo": "https://cdn.example.com/logos/chrome.png",
  "type": "browser",
  "vendor": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Google LLC",
    "url": "https://about.google"
  },
  "categories": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Productivity"
    }
  ],
  "created_at": "2025-06-15T10:00:00.000Z",
  "updated_at": "2026-01-20T14:30:00.000Z"
}

Current generated contract shape​

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "canonical_name": "Google Chrome",
  "type": "browser",
  "vendor": "Google LLC",
  "vendor_url": "https://about.google",
  "description": "A cross-platform web browser developed by Google",
  "display_colour": "#4285F4",
  "logo": "https://cdn.example.com/logos/chrome.png",
  "categories": [
    {
      "category_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Productivity"
    }
  ],
  "url_patterns": [
    {
      "id": "11223344-5566-7788-99aa-bbccddeeff00",
      "pattern": "*.google.com"
    }
  ],
  "desktop_aliases": [
    {
      "id": "44556677-8899-aabb-ccdd-eeff00112233",
      "alias": "chrome.exe"
    }
  ]
}

2. catalog-apps detail embeds data the docs say should not be embedded​

The docs explicitly say url_patterns and desktop_aliases are not part of CatalogApp and should be fetched separately:

The generated detail schema includes both arrays directly on CatalogAppDetailDto:

  • services/amm/agent-web-api/openapi.json#L13120

Documented endpoint design​

GET /v2/catalog-apps/{catalog_app_id}
GET /v2/catalog-apps/{catalog_app_id}/url-patterns
GET /v2/catalog-apps/{catalog_app_id}/desktop-aliases

Current generated detail payload​

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "canonical_name": "Google Chrome",
  "url_patterns": [
    {
      "id": "11223344-5566-7788-99aa-bbccddeeff00",
      "pattern": "*.google.com"
    }
  ],
  "desktop_aliases": [
    {
      "id": "44556677-8899-aabb-ccdd-eeff00112233",
      "alias": "chrome.exe"
    }
  ]
}

3. catalog-apps path parameter naming differs from the docs​

The docs use catalog_app_id for catalog-app path parameters:

The generated OpenAPI uses id for the same path parameter:

  • services/amm/agent-web-api/openapi.json#L4343
  • services/amm/agent-web-api/openapi.json#L4513

Documented parameter examples​

GET /v2/catalog-apps/{catalog_app_id}
GET /v2/catalog-apps/{catalog_app_id}/url-patterns
GET /v2/catalog-apps/{catalog_app_id}/desktop-aliases

Current generated parameter examples​

GET /v2/catalog-apps/{id}
GET /v2/catalog-apps/{id}/url-patterns
GET /v2/catalog-apps/{id}/desktop-aliases

4. catalog-apps/\{catalog_app_id\}/url-patterns is missing documented query params​

The docs include q, sort_by, and sort_order:

The generated OpenAPI does not expose q, sort_by, or sort_order:

  • services/amm/agent-web-api/openapi.json#L4573

Documented request example​

GET /v2/catalog-apps/{catalog_app_id}/url-patterns?q=google&sort_by=pattern&sort_order=asc

Current generated request shape​

GET /v2/catalog-apps/{id}/url-patterns

5. catalog-apps/\{catalog_app_id\}/desktop-aliases is missing documented query params​

The docs include q, sort_by, and sort_order:

The generated OpenAPI does not expose q, sort_by, or sort_order:

  • services/amm/agent-web-api/openapi.json#L4667

Documented request example​

GET /v2/catalog-apps/{catalog_app_id}/desktop-aliases?q=chrome&sort_by=alias&sort_order=asc

Current generated request shape​

GET /v2/catalog-apps/{id}/desktop-aliases

6. catalog-vendors schema does not match the docs​

The docs define url as nullable string:

The generated schema types url as nullable object:

  • services/amm/agent-web-api/openapi.json#L12841

Documented shape​

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "Google LLC",
  "url": "https://about.google"
}

Current generated contract shape​

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "Google LLC",
  "url": {}
}

7. catalog-categories schema does not match the docs​

The docs say category DTOs are only id and name, and explicitly omit timestamps:

The generated schema requires created_at and updated_at:

  • services/amm/agent-web-api/openapi.json#L12754

Documented shape​

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "Productivity"
}

Current generated contract shape​

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "Productivity",
  "created_at": "2025-06-15T10:00:00.000Z",
  "updated_at": "2026-01-20T14:30:00.000Z"
}

8. Error/status documentation differs​

The docs list 403 for vendors, categories, app detail, url-patterns, and desktop-aliases:

The generated OpenAPI does not document 403 for those routes, and vendors also does not document 401:

  • /v2/catalog-vendors in services/amm/agent-web-api/openapi.json#L4233
  • /v2/catalog-categories in services/amm/agent-web-api/openapi.json#L4125
  • /v2/catalog-apps/{id} in services/amm/agent-web-api/openapi.json#L4508

Documented status set example​

401
403
404
500

Current generated status set example for GET /v2/catalog-apps/{id}​

200
401
404
500

Notes​

catalog-apps/summary looks aligned​

I did not find a mismatch between:

catalog-apps list should follow CatalogApp​

The intended contract is that the list endpoint returns CatalogApp[], not a lighter list-specific DTO. That means the backend list implementation and generated OpenAPI should be updated to match the documented CatalogApp shape for list responses as well as detail responses.

Requested Action​

Please update the NestJS DTOs, decorators, and controller metadata so that the generated OpenAPI matches the documented v2 catalog API in docs/api, then regenerate services/amm/agent-web-api/openapi.json and validate the contract.