| No | "search" | Operation mode. Accepts "search" or "recommend". |
| articleId | string | Conditional | "" | UUID of the reference article. Required when type=recommend. |
Request Examples
Search Request
GET /api/search?q=async+await&type=search
Recommendation Request
GET /api/search?type=recommend&articleId=550e8400-e29b-41d4-a716-446655440000
Standard HTTP headers apply. While not strictly required for this endpoint, including Accept: application/json is recommended for consistent parsing behavior.
All responses return a 200 OK status with a JSON payload. Database or runtime errors return a 500 Internal Server Error with an error message.
Success Response (200)
The response structure varies slightly depending on the type parameter.
Search Mode Response
{
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"slug": "understanding-async-await",
"titleEn": "Understanding Async/Await in JavaScript",
"excerptEn": "A deep dive into asynchronous programming patterns...",
"difficultyLevel": "intermediate",
"series": {
"slug": "js-fundamentals",
"title": "JavaScript Fundamentals"
},
"categories": [
{ "slug": "javascript", "name": "JavaScript" }
],
"tags": [
{ "slug": "async", "name": "Async" },
{ "slug": "promises", "name": "Promises" }
]
}
]
}
Recommendation Mode Response
{
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"slug": "event-loop-deep-dive",
"titleEn": "Event Loop Deep Dive",
"excerptEn": "How the call stack and callback queue interact...",
"difficultyLevel": "advanced",
"series": {
"slug": "js-fundamentals",
"title": "JavaScript Fundamentals"
}
}
]
}
Error Responses
| Status Code | Description | Example Payload |
|---|
200 | Empty results (query too short or no matches) | {"results": []} |
500 | Database or runtime error | {"error": "relation \"Article\" does not exist"} |
Note: The endpoint gracefully handles short queries (q.length < 2) by returning an empty results array rather than a 400 Bad Request.
Usage Example
cURL: Search
curl -X GET "https://api.codcompass.com/api/search?q=react+hooks&limit=10" \
-H "Accept: application/json"
cURL: Recommendations
curl -X GET "https://api.codcompass.com/api/search?type=recommend&articleId=550e8400-e29b-41d4-a716-446655440000" \
-H "Accept: application/json"
JavaScript (Fetch)
async function fetchSearchResults(query) {
const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
const data = await res.json();
return data.results;
}
async function fetchRecommendations(articleId) {
const res = await fetch(`/api/search?type=recommend&articleId=${articleId}`);
const data = await res.json();
return data.results;
}
Common Pitfalls
-
Minimum Query Length Requirement
The search logic explicitly checks q.length < 2 and returns an empty array if the condition is met. Always validate or pad client-side inputs before making requests to avoid unnecessary network calls.
-
Series-Driven Recommendations
While the endpoint accepts an articleId for recommendations, the current implementation prioritizes articles sharing the same seriesId. Tag-based matching is fetched but not actively used in the filtering logic. If an article lacks a series, the endpoint falls back to returning any 5 published articles excluding the reference ID.
-
Published-Only Filter
Both search and recommendation modes enforce isPublished = true. Draft, archived, or scheduled articles will never appear in results. Ensure your content management workflow aligns with this visibility constraint.
GET /api/articles/{slug} — Retrieve full article content, metadata, and navigation links. Use this to render the actual content after a search or recommendation click.GET /api/series — List all content series with pagination and ordering. Useful for building series index pages or filtering search results by series.GET /api/tags — Fetch available tags and their associated article counts. Can be combined with search results to build faceted navigation or tag clouds.
