search

/search/ endpoint in QA

/search/ endpoint in SWAGGER-UI

curl -X 'GET' \ 'http://peviitorqa.go.ro/api/v0/search/?q=<string>&start=<integer>&rows=<integer>&sort=<string>' \ -H 'accept: application/json'

---

---

Technical Documentation: Search Endpoint

Request and Response Structure

• Method: GET

• Endpoint name: /search

• Request Parameters:

  • q – Search query string (required).
  • start – The starting index for pagination.
  • rows – Number of job records to retrieve per request.
  • sort – Sorting criteria (e.g., date, relevance).

• Response Format: application/json; charset=utf-8

Expected Data Format

{
    "response": {
        "numFound": <integer>,
        "docs": [
            { "job_title": ["<array>"], 
              "company": ["<array>"], 
              "city": ["<array>"], 
              "remote": ["<array>"], 
              "job_link": ["<array>"], 
              "id": "<string>" 
            }
        ]
    }
}

List of Status Codes and Error Messages

• 200 OK – Request successful, returns list of companies and job counts if applicable.
• 400 Bad Request – Invalid request parameters or missing required fields.
• 401 Unauthorized – Authentication is required or invalid credentials.
• 403 Forbidden – Access denied due to insufficient permissions.
• 404 Not Found – The requested endpoint or resource does not exist.
• 405 Method Not Allowed – Only GET requests are supported.
• 500 Internal Server Error – An unexpected error occurred on the server.
• 502 Bad Gateway – The primary and fallback servers are both unreachable.
• 503 Service Unavailable – The SOLR server is down or unreachable.
• 507 Insufficient Storage – SOLR or API server runs out of space/memory.

{
    "error": "<message>",
    "code": "<number>"
}

Business Logic Applied

• Normalizes search parameters (e.g., removes diacritics).
• Constructs SOLR query with filters for search string, start index, row count, and sorting.
• Implements pagination using start and rows parameters.
• Falls back to backup server if SOLR is unavailable.

Security Measures

• CORS policy: Open to all (Access-Control-Allow-Origin: *).
• Rate Limits: Not implemented but recommended.

Dependencies

• SOLR Search Server – Required to fetch job data.
• PHP file_get_contents function – Communicates with SOLR API.

Known Limitations & Edge Cases

• SOLR Downtime: If SOLR is unavailable, API returns a 503 error.
• Empty Dataset: If no jobs exist, API returns "There are no jobs to display".
• Non-negative counts: total and start will always be a non-negative integer.
• Non-empty string: All fields must be non-empty.
• No Results: Returns 404 Not found if no jobs are found.
• Invalid Parameters: If parameters are invalid or null, API returns a 400 Bad Request error.
• Pagination: Managed via start and rows parameters.
• Security Risks: No authentication currently implemented.
• To do: Add API keys.
• To do: Prevent abuse.
• To do: Implement security.json and IP whitelisting.

---

---

Business Requirement Document: Search Jobs Endpoint

Objective:

The objective of this project is to develop an API endpoint that allows users to search for jobs in a SOLR index. This endpoint will provide users with relevant job listings based on their search queries.

Key Requirements:

1. Functionality:

   • The endpoint should accept a search query as input.
   • It should return a list of job listings that match the search query.

2. Error Handling:

   • The endpoint should handle errors gracefully, providing meaningful error messages to users.
   • Specific error handling should include scenarios where no search query is provided or no results are found.

3. User Experience:

   • The endpoint should respond quickly to ensure a seamless user experience.
   • The response should include clear and relevant job listings.

4. Data Integrity:

   • Ensure that the search results are accurate and relevant to the query.
   • The endpoint should only return job listings that are present in the SOLR index.

5. Security:

   • Implement appropriate security measures to protect user data and prevent unauthorized access to the SOLR index.

6. Scalability:

   • The endpoint should be designed to handle a high volume of requests without impacting performance.

Acceptance Criteria:

• The endpoint successfully retrieves job listings from the SOLR index based on the search query.
• The endpoint returns relevant results that match the query.
• Error messages are clear and informative for users.
• The endpoint responds within an acceptable time frame.

Assumptions and Dependencies:

• The SOLR index is properly configured and populated with job data.
• Necessary infrastructure and resources are available to support the endpoint.

Risks and Mitigation Strategies:

• Risk: Technical issues with the SOLR index could prevent search results from being retrieved.

  • Mitigation: Regularly monitor the SOLR index for errors and perform maintenance as needed.

• Risk: High traffic could impact performance.

  • Mitigation: Implement load balancing and optimize server resources to handle increased traffic.

• Risk: Inaccurate search results could lead to poor user experience.

  • Mitigation: Regularly validate the search functionality to ensure relevance and accuracy of results.

---