Filter Docs Index By Query
Return the docs index filtered by the q query parameter. The public and authenticated docs routes use the same filter rules; the authenticated route only adds the app API login requirement.
In this article
Use this guide when you need the JSON docs index to prove that a search term was applied by the server before the index reached a documentation consumer.
The public and app docs prefixes share the same index builder and matching logic. The visible Docs search in the landing wiki and native app currently filters the already-loaded index locally, so use JSON API captures as the evidence for q filtering.
Before you start
- Use an index route with no article or asset path after docs: /api/public/docs or /api/app/docs.
- Use GET when you need the filtered JSON index body. HEAD is accepted by the handler but does not return that body.
- Ensure the docs content service can load articles.json from DOCS_CONTENT_PATH or the default docs content path.
- Use /api/app/docs only from an authenticated app API request, such as the Harbor Demo User session in the GB demo runtime.
- For GB captures, use locale=en or locale=en-GB and provide DOCS_API_BASE_URL to the capture runner.
Instructions
- 1.
Choose the docs index route
Use GET /api/public/docs for an unauthenticated filtered index check. Use GET /api/app/docs only when you need to show the same filter behind app authentication. Do not add an article slug or assets segment, because q filtering only applies to the index route.
- 2.
Set locale and query
For the GB manual context, request locale=en or locale=en-GB. English locales normalise to en. Put the search term in q, such as booking for the public docs check or pos for the authenticated app docs check.
- 3.
Request the filtered index
Send the GET request and wait for the JSON response. The handler loads the docs content bundle before applying request options and the q filter.
- 4.
Check the response summary
Confirm that the response includes version, locale, platform, query, article_count, and sections. Each section contains article summaries, not full article detail. A query with no matches still returns 200 OK with article_count set to 0 and an empty sections array.
- 5.
Interpret the matching rules
The service filters by locale first, then performs a simple case-insensitive substring match across the implemented article text fields. It is a global docs search over the bundled articles, not a Harbor Demo Group, Harbor Soho, role, booking, POS, catalogue, or location data filter.
- 6.
Separate API filtering from visible search
Use the JSON API captures as evidence for server-side q filtering. The current landing Wiki and native Documentation search boxes filter the already-loaded index locally and do not send q in their index requests.
Validations and limits
- Only GET and HEAD are accepted by the shared docs handler; other methods return 405 metodo no permitido.
- The public prefix does not require an authenticated user; the app prefix must pass app API authentication before docs filtering runs.
- If q is absent or trims to empty, the index is filtered only by locale and the query field is omitted from JSON.
- q is trimmed only; there is no length, character, token, syntax, fuzzy, stemming, ranking, pagination, highlighting, or accent-folding support.
- locale, platform or device, and theme are normalised rather than rejected; en-GB normalises to en and unsupported locales fall back to es.
- Searchable fields are ID, SourceGuideID, ActionID, PrimaryKeyword, Category, Title, Summary, Result, Intro, Prerequisites, Validations, and each step Title and Description.
- article_count is recomputed from the filtered section articles.
- The visible /docs search surface is supporting context only and must not be presented as proof that q was sent to the server.
Expected result
You have a localized docsIndexResponse whose query, article_count, and sections reflect the server-side q filter for the selected locale and prefix.