total

/total/ endpoint in QA

/total/ endpoint in SWAGGER-UI

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

---

---

Technical Documentation

Request and Response Structure

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

Expected Data Format

{
  "total": {
    "jobs": "<number>",
    "companies": "<number>"
  }
}

• "jobs": Total number of jobs available.
• "companies": Number of companies that have at least one job listing.

List of Status Codes and Error Messages

• 200 OK – Request successful, returns total job and company count.

• 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).
• Uses facet fields to count unique companies that have job postings.
• Jobs are counted based on the numFound field in SOLR’s response.
• Companies with at least one job posting are included in the count.

Database Schema Used

• The API retrieves job and company data from a SOLR search index (jobs core).
• Uses facet counting on company_str to determine how many unique companies have job listings.

Business Logic Applied

• Queries all job listings using q=*:*.
• Uses faceting (facet.field=company_str) to count the number of unique companies.
• Only companies with at least one job posting are included in the count.

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 and company 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, it must display "There are no jobs to display.".
• Non-negative counts: jobs and companies will always be a non-negative integer.
• Performance Issues: Large datasets may cause response delays due to SOLR faceting.
• TBD: Max number of documents in PROD giving the infrastructure Raspberry Pi 5.
• To do: secure SOLR with security.json
• To do: protect SOLR by IP whitelist

---

---

Business Requirement Document: Retrieve Total Job and Company Counts from SOLR Index

Objective:

The objective of this project is to develop an API endpoint that retrieves the total number of jobs and companies from a SOLR index. This endpoint will be used to provide users with an overview of the job market by company.

Key Requirements:

1. Functionality:

   • The endpoint should retrieve the total number of jobs available in the SOLR index.
   • It should also retrieve the total number of companies that have at least one job listing.
   • The endpoint should return both counts in a single response.

2. Error Handling:

   • The endpoint should handle errors gracefully, providing meaningful error messages to users.
   • Specific error handling should include scenarios where technical issues prevent data retrieval from the SOLR index.

3. User Experience:

   • The endpoint should respond quickly to ensure a seamless user experience.
   • The response should include clear and concise counts for both jobs and companies.

4. Data Integrity:

   • Ensure that the retrieved counts are accurate and up-to-date.
   • The endpoint should only count companies with at least one active job listing.

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 the total number of jobs from the SOLR index.
• The endpoint correctly counts the number of companies with at least one job listing.
• 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 data 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.

• Risk: Data inconsistencies could lead to incorrect counts.

  • Mitigation: Regularly validate data integrity in the SOLR index.

---