[codex] document canonical /api base URL for Search API#140
Closed
[codex] document canonical /api base URL for Search API#140
Conversation
Deploying qf-api-docs with
|
| Latest commit: |
c9244cc
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0bd3a1ef.qf-api-docs.pages.dev |
| Branch Preview URL: | https://codex-document-search-api-ca.qf-api-docs.pages.dev |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Quran.Foundation Search API documentation to publish /search/api as the canonical base URL (aligning with other API families) while explicitly noting that the legacy /search base URL remains supported for backward compatibility.
Changes:
- Updated the Search API OpenAPI
serversURLs to use/search/apifor both production and pre-production. - Added a canonical-base-URL + backward-compatibility note to the Search API description/introduction.
- Regenerated the affected “latest” and
1.0.0Search API docs pages to reflect the new canonical base URL.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| openAPI/search/v1.json | Sets canonical server base URLs to /search/api and documents legacy /search support. |
| docs/search_apis_versioned/search-controller-search.api.mdx | Regenerated operation doc to reference /search/api servers and include canonical URL note. |
| docs/search_apis_versioned/quran-foundation-search-api.info.mdx | Regenerated intro doc to include canonical base URL + backward-compat note. |
| docs/search_apis_versioned/1.0.0/search-controller-search.api.mdx | Same regeneration for version 1.0.0 operation doc with /search/api servers. |
| docs/search_apis_versioned/1.0.0/quran-foundation-search-api.info.mdx | Same regeneration for version 1.0.0 intro doc with canonical base URL note. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
osamasayed
requested changes
Apr 22, 2026
| "info": { | ||
| "title": "Quran.Foundation Search API", | ||
| "description": "Quran.Foundation Search API provides programmatic access to search Quran content including verses, chapters, juz, pages, and translations. This is distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).\n\n## How to get access\n\nWe are using OAuth2 flows to authenticate and authorize requests. To get started, you need to [get an access token](/docs/tutorials/oidc/getting-started-with-oauth2#obtaining-oauth-20-client-credentials) to make requests to our APIs. Then follow the steps mentioned [here](/docs/tutorials/oidc/getting-started-with-oauth2). The required scope is [`search`](/docs/user_related_apis_versioned/scopes#search).", | ||
| "description": "Quran.Foundation Search API provides programmatic access to search Quran content including verses, chapters, juz, pages, and translations. This is distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).\n\n## How to get access\n\nWe are using OAuth2 flows to authenticate and authorize requests. To get started, you need to [get an access token](/docs/tutorials/oidc/getting-started-with-oauth2#obtaining-oauth-20-client-credentials) to make requests to our APIs. Then follow the steps mentioned [here](/docs/tutorials/oidc/getting-started-with-oauth2). The required scope is [`search`](/docs/user_related_apis_versioned/scopes#search).\n\nUse the canonical base URL `https://apis.quran.foundation/search/api` (or `https://apis-prelive.quran.foundation/search/api` in pre-production). The legacy base URL without `/api` remains supported for backward compatibility.", |
Member
There was a problem hiding this comment.
This PR once merged should push new search definition to the docs repo so we don't need to manually do this.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/search/apias the canonical base URL/searchbase URL still works1.0.0Why
The Search API docs were the outlier among the QF API families because they omitted the
/apisegment from the published base URL. That inconsistency has been confusing developers who expect the same URL shape used by the other APIs.This PR updates the docs to point developers at the canonical
/apiform while still documenting that the old base URL remains valid.Reviewer Notes
Validation
openAPI/search/v1.json1.0.0search docs now reference the canonical/search/apibase URL