random

/random/ endpoint in QA

/random/ endpoint in SWAGGER-UI

curl -X 'GET' \ 'http://peviitorqa.go.ro/api/v0/random/' \ -H 'accept: application/json'

---

---

Technical Documentation

Request and Response Structure

• Method: GET
• Endpoint name: /random
• Request Parameters: None
• Response Format: application/json; charset=utf-8

Expected Data Format

{
  "response": {
    "numFound": "<number>",
    "start": "<number>",
    "numFoundExact": true,
    "docs": [
      {
        "job_link": [
          "<string>"
        ],
        "job_title": [
          "<string>"
        ],
        "company": [
          "<string>"
        ],
        "company_str": "<string>",
        "hiringOrganization.name": [
          "<string>"
        ],
        "country": [
          "<string>"
        ],
        "city": [
          "<string>"
        ],
        "remote": [
          "<string>"
        ],
        "id": "<UUID>"
      }
    ]
  }
}

• numFound: Total number of job postings available in the SOLR index.
• start: The offset for the randomly selected job.
• numFoundExact: Boolean flag indicating if the count is exact.
• docs: Contains job details.
• job_link: URL to apply for the job.
• job_title: The title of the job.
• company: The company offering the job.
• company_str: The string representation of the company name.
• hiringOrganization.name: Alternative field for the company name.
• country: Its value is always România.
• city: The city where the job is located.
• remote: Specifies if the job is remote, hybrid, or on-site.
• id: Unique identifier for the job posting.

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>"
  }

Specific Conditions or Filters Applied

• Fetches job data from the SOLR search index (jobs core).
• If there are no jobs available, returns {"message": "There are no jobs to display"}.
• Selects a random job from the available dataset using SOLR’s start parameter.

Database Schema Used

• Queries SOLR search index (jobs core) for job data.
• Uses numFound from the initial query to determine the total number of jobs.
• Selects a random job using the start parameter in a follow-up request.

Business Logic Applied

• Queries all job listings using q=*:* and rows=0 to count total jobs.
• If no jobs are found, returns a "There are no jobs to display" message.
• Randomly selects a job using start=<random_number>.
• If SOLR is unavailable, a 503 Service Unavailable error is returned.

Security Measures

• CORS policy: Open to all (Access-Control-Allow-Origin: *).
• Authentication & Authorization: Not implemented in current version.
• Rate Limits: Not specified but should be considered for production.

Dependencies

• SOLR Search Server – Required to fetch job data.
• PHP file_get_contents function – Fetches SOLR API response.

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: numFound and start will always be a non-negative integer.
• Non-empty string: All fields must be non-empty.
• Performance Issues: Large datasets may cause response delays due to SOLR queries.
• Random Job Selection: Some jobs may be retrieved more frequently due to SOLR’s underlying data distribution.
• To do: Secure SOLR with security.json.
• To do: Protect SOLR by IP whitelist.

---

---

Business Requirement Document: Retrieve a Random Job from SOLR Index

Objective:

The objective of this project is to develop an API endpoint that retrieves a random job from a SOLR index. This endpoint will be used to provide users with a random job listing, enhancing user engagement and exploration of job opportunities.

Key Requirements:

1. Functionality:

   • The endpoint should retrieve a single random job from the SOLR index.
   • The job should be selected randomly from all available jobs in the index.

2. Error Handling:

   • The endpoint should handle errors gracefully, providing meaningful error messages to users.
   • Specific error handling should include scenarios where no jobs are available in the index or when technical issues prevent job retrieval.

3. User Experience:

   • The endpoint should respond quickly to ensure a seamless user experience.
   • The response should include all relevant details about the job, such as job title, description, and company name.

4. Data Integrity:

   • Ensure that the retrieved job data is accurate and up-to-date.
   • The endpoint should not return jobs that have been removed or are no longer active.

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 a random job from the SOLR index.
• Error messages are clear and informative for users.
• The endpoint responds within an acceptable time frame.
• Retrieved job data is accurate and relevant.

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 job retrieval.

  • 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.