This is the Django RESTful API Documentation. For ease of consumption, the tables are grouped based on endpoint base.
The Opportunity Endpoints:
| Endpoint | HTTP Methods | Description | Parameters | Response Example |
|---|---|---|---|---|
| /api/email_opportunity/ | GET | – GET: Retrieve a list of all email opportunities. | None for GET | – GET: List of email opportunities. |
| POST | – POST: Create a new email opportunity. | POST: JSON body | – POST: Status 201 Created on success. | |
| /api/email_opportunity/{id} | GET | – GET: Retrieve a specific email opportunity. | id (URL parameter) | – GET: Details of the specific email opportunity. |
| PUT | – PUT: Update a specific email opportunity. | – PUT: Status 204 No Content on success. | ||
| DELETE | – DELETE: Delete a specific email opportunity. | – DELETE: Status 204 No Content on success. | ||
| /api/email_opportunity/active/ | GET | Retrieve all active email opportunities for the authenticated user, excluding certain statuses. | None | List of active email opportunities. |
The Job Site Endpoints:
| Endpoint | HTTP Method | Description | Parameters | Response | Status Codes |
|---|---|---|---|---|---|
| /api/job_site/ | GET | Retrieves a list of job sites associated with the authenticated user. | No parameters. | List of serialized job sites associated with the user. | 200 OK |
| /api/job_site/ | POST | Creates a new job site for the authenticated user. | Request body must include job site data (e.g., name, description). | Success: Returns status 201 if job site is created successfully. Error: Returns validation errors if data is invalid. | 201 Created, 400 Bad Request |
| /api/job_site/([0-9]*)/postings | GET | Retrieves a list of job postings associated with a specific job site. | job_site_id (integer) — the ID of the job site. | List of job postings for the specified job site. | 200 OK |
| /api/job_site/([0-9]*)/postings | POST | Creates a new job posting associated with a specific job site. | job_site_id (integer) — the ID of the job site, request body includes job posting data (e.g., job title, description). | Success: Returns status 201 if job posting is created. Error: Returns validation errors if data is invalid. | 201 Created, 400 Bad Request |
| /api/job_site/([0-9]*) | GET | Retrieves details of a specific job site based on its primary key (ID). | pk (integer) — the ID of the job site. | Details of the job site (serialized data). | 200 OK |
| /api/job_site/([0-9]*) | PUT | Updates an existing job site associated with the authenticated user. | pk (integer) — the ID of the job site, request body must include updated job site data. | Success: Returns status 204 if job site is updated. Error: Returns validation errors if data is invalid. | 204 No Content, 400 Bad Request, 403 Forbidden |
| /api/job_site/([0-9]*) | DELETE | Deletes a specific job site associated with the authenticated user. | pk (integer) — the ID of the job site. | Success: Returns status 204 if job site is deleted. | 204 No Content, 403 Forbidden |
Job Posting Endpoints:
| Endpoint Name | HTTP Method | Description | Parameters | Response | Status Codes |
|---|---|---|---|---|---|
| /api/job_posting/active/ | GET | Retrieves the active job postings for the authenticated user, filtering based on status. | No parameters, requires authenticated user. | List of active job postings for the user. | 200 OK, 401 Unauthorized, 204 No Content |
| /api/job_posting/ | GET | – GET: Retrieves a list of job postings for the authenticated user. | GET: No parameters, requires authenticated user. | – GET: List of job postings. | 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized |
| POST | – POST: Creates a new job posting for the authenticated user. | POST: company_name, posting_title, etc. | – POST: Status 201 Created on success, or validation errors. | ||
| /api/job_posting/([0-9]+) | GET | – GET: Retrieves the details of a specific job posting. | pk: The ID of the job posting. | – GET: Serialized job posting details. | 200 OK, 204 No Content, 400 Bad Request, 403 Forbidden, 404 Not Found |
| PUT | – PUT: Updates a specific job posting. | – PUT: Status 204 No Content on success. | |||
| DELETE | – DELETE: Deletes a specific job posting. | – DELETE: Status 204 No Content. | |||
| /api/report/(?P | GET | Retrieves a report based on the report type and optional reference date. Valid report types: postingsAppliedSince, perSite, perWeek. | report_type: The report type (postingsAppliedSince). reference_date: Optional date (ISO format). | A generated report based on the specified type. Contains metadata and report data. | 200 OK, 400 Bad Request, 401 Unauthorized |
User Authentication and Profile Endpoints:
| Endpoint Name | HTTP Method | Description | Parameters | Response | Status Codes |
|---|---|---|---|---|---|
| register_user | POST | Registers a new user with provided details, including required and optional fields. | username (string), email (string), first_name (string), last_name (string), password (string) | On success: {“message”: “User successfully registered.”} On failure: {“error”: “Username already exists.”} | 201 Created, 400 Bad Request |
| authenticate_user | POST | Authenticates a user and returns JWT tokens for successful login. | username (string), password (string) | On success: {“access”: “access_token”, “refresh”: “refresh_token”, “user”: {user data}} On failure: {“error”: “Invalid credentials.”} | 200 OK, 400 Bad Request, 401 Unauthorized |
| logout_user | POST | Logs out a user by blacklisting the refresh token. | refresh (string) | On success: {“detail”: “Successfully logged out.”} On failure (no token): {“detail”: “No refresh token provided.”} On failure (invalid token): {“detail”: “Invalid token.”} | 200 OK, 400 Bad Request |
| update_user_info | PUT | Allows an authenticated user to update their profile information. | first_name (string), last_name (string), email (string), password (string, optional) | On success: {“message”: “User info updated successfully.”} On failure: {“email”: [“Enter a valid email address.”]} | 200 OK, 400 Bad Request |
| list_all_users | GET | Retrieves a list of all users (admin access required). | None | On success: [{user data}, {user data}, …] | 200 OK, 403 Forbidden |
| token_obtain_pair | POST | Obtains JWT tokens using credentials for authentication. | username (string), password (string) | On success: {“access”: “access_token”, “refresh”: “refresh_token”} On failure: {“detail”: “Invalid credentials.”} | 200 OK, 400 Bad Request |
| token_refresh | POST | Refreshes an expired JWT access token using the provided refresh token. | refresh (string) | On success: {“access”: “new_access_token”} On failure: {“detail”: “Token refresh failed. Please log in again.”} | 200 OK, 401 Unauthorized, 500 Internal Server Error |
| user_profile | GET | Retrieves the profile data of the current authenticated user. | None | On success: {“id”: 1, “username”: “john_doe”, “email”: “john_doe@example.com”, “first_name”: “John”, “last_name”: “Doe”} | 200 OK, 401 Unauthorized |