Skip to content

docs: align API documentation with current behavior - #158

Merged
jdaigneau5 merged 1 commit into
devfrom
af/documentation-refresh
Sep 23, 2026
Merged

jdaigneau5 merged 1 commit into
devfrom
af/documentation-refresh

Conversation

@afoote-mitre

Copy link
Copy Markdown
Collaborator

Summary

Bring the public documentation and examples into line with the current API implementation. This PR changes no request handling, search matching, runtime configuration values, dependency versions, or response behavior.

Changes and Rationale

Change Why it was needed Primary files
Correct local setup and runtime guidance Preserve the tracked environment template with cp, use the lockfile through npm ci, explain the Node.js 24 baseline and conflicting upstream engine declaration, and distinguish the API's default port 3000 from Postman's port 4000. README.md, test/postman/README.md
Clarify search matching Missing selected-container data does not prevent exclusion filters from matching. Explain keyword prefix matching and analyzed phrase matching, and correct the isVulnerable restriction to apply only when true. README.md, routes/swagger.js, api-docs/openapi.json
Complete /webSearch request/error documentation The existing validator requires sort.property when sort is supplied, but the schema did not. Document that requirement and the existing HTTP 400 error-body schema without changing validation. routes/index.js, api-docs/openapi.json, README.md
Correct operational descriptions Readiness uses an overall deadline across field-capability and search operations. Enabled health-check logging still follows the success sample rate. TLS settings control server-certificate verification. README.md, config/default.jsonc, config/devel.jsonc, config/custom-environment-variables.jsonc
Align fault-injection instructions with error handling Connectivity failures trigger the collection's 503 search assertion; upstream 403/404 errors map to 502 on /search, while readiness reports 503. The instructions previously treated these as interchangeable. test/postman/README.md
Remove obsolete example settings and improve navigation Telemetry settings no longer have consumers. Separate raw-query, operational, semantic-search, and container-check guidance; distinguish packaging/liveness checks from dependency readiness, and request-scoped PIT from cross-request pagination consistency. .env.example, README.md

Scope

  • /webSearch remains supported; no deprecation or removal is introduced.
  • The current bounded semantic-search behavior and public pagination window are unchanged. This PR does not enable PIT or add caching, queueing, rate limiting, or telemetry.
  • OpenAPI JSON is regenerated from its source descriptions. Configuration edits are comments only; .env.example loses only unused settings.

@afoote-mitre afoote-mitre self-assigned this Sep 23, 2026
@jdaigneau5
jdaigneau5 merged commit 20674b6 into dev Sep 23, 2026
1 check 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.

2 participants