Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
245 lines (204 loc) · 7.37 KB

API_DOCUMENTATION.md

File metadata and controls

245 lines (204 loc) · 7.37 KB

JobTracker API Documentation

This document provides an overview of the CRUD API endpoints built for the JobTracker application using ASP.NET Core Controllers.

Base URL

http://localhost:5138

OpenAPI Documentation

The API includes OpenAPI/Swagger documentation available at:

http://localhost:5138/openapi/v1.json

Controllers Overview

1. Users Controller (/api/users)

Endpoints:

  • GET /api/users - Get all active users
  • GET /api/users/{id} - Get user by ID
  • POST /api/users - Create new user
  • PUT /api/users/{id} - Update user
  • DELETE /api/users/{id} - Archive user (soft delete)
  • GET /api/users/archived - Get archived users
  • POST /api/users/{id}/restore - Restore archived user

DTOs:

  • UserDto - Full user representation
  • CreateUserDto - User creation payload
  • UpdateUserDto - User update payload (partial)

2. Companies Controller (/api/companies)

Endpoints:

  • GET /api/companies - Get all active companies
  • GET /api/companies/{id} - Get company by ID
  • POST /api/companies - Create new company
  • PUT /api/companies/{id} - Update company
  • DELETE /api/companies/{id} - Archive company (soft delete)
  • POST /api/companies/{id}/external-ids - Add external ID to company
  • GET /api/companies/archived - Get archived companies
  • POST /api/companies/{id}/restore - Restore archived company
  • GET /api/companies/{id}/job-postings - Get job postings for company

DTOs:

  • CompanyDto - Full company representation
  • CreateCompanyDto - Company creation payload
  • UpdateCompanyDto - Company update payload (partial)
  • AddExternalIdDto - External ID addition payload

3. Job Postings Controller (/api/jobpostings)

Endpoints:

  • GET /api/jobpostings - Get all active job postings
  • GET /api/jobpostings/{id} - Get job posting by ID
  • POST /api/jobpostings - Create new job posting
  • PUT /api/jobpostings/{id} - Update job posting
  • DELETE /api/jobpostings/{id} - Archive job posting (soft delete)
  • POST /api/jobpostings/{id}/external-ids - Add external ID to job posting
  • POST /api/jobpostings/{id}/salary-range - Set salary range for job posting
  • POST /api/jobpostings/{id}/language-requirements - Add language requirement
  • GET /api/jobpostings/archived - Get archived job postings
  • POST /api/jobpostings/{id}/restore - Restore archived job posting
  • GET /api/jobpostings/search - Search job postings with filters

DTOs:

  • JobPostingDto - Full job posting representation
  • CreateJobPostingDto - Job posting creation payload
  • UpdateJobPostingDto - Job posting update payload (partial)
  • AddExternalIdDto - External ID addition payload
  • SetSalaryRangeDto - Salary range setting payload
  • AddLanguageRequirementDto - Language requirement addition payload

4. Job Applications Controller (/api/jobapplications)

Endpoints:

  • GET /api/jobapplications - Get all active job applications (with optional filters: userId, jobPostingId, status)
  • GET /api/jobapplications/{id} - Get job application by ID
  • POST /api/jobapplications - Create new job application
  • PUT /api/jobapplications/{id} - Update job application
  • DELETE /api/jobapplications/{id} - Archive job application (soft delete)
  • PUT /api/jobapplications/{id}/status - Update application status
  • POST /api/jobapplications/{id}/notes - Add note to application
  • PUT /api/jobapplications/{id}/followup - Schedule follow-up
  • POST /api/jobapplications/{id}/followup - Record follow-up
  • GET /api/jobapplications/archived - Get archived job applications
  • POST /api/jobapplications/{id}/restore - Restore archived job application
  • GET /api/jobapplications/stats - Get application statistics (with optional userId filter)

DTOs:

  • JobApplicationDto - Full job application representation
  • CreateJobApplicationDto - Job application creation payload
  • UpdateJobApplicationDto - Job application update payload (partial)
  • UpdateApplicationStatusDto - Status update payload
  • AddApplicationNoteDto - Note addition payload
  • ScheduleFollowUpDto - Follow-up scheduling payload
  • RecordFollowUpDto - Follow-up recording payload

Application Status Values:

  • 0 - Applied
  • 1 - InReview
  • 2 - PhoneScreening
  • 3 - TechnicalInterview
  • 4 - OnSiteInterview
  • 5 - FinalInterview
  • 6 - Offered
  • 7 - Accepted
  • 8 - Rejected
  • 9 - Withdrawn

Common Features

Soft Delete Architecture

All entities support soft deletion through the ArchivedAt property:

  • DELETE operations set ArchivedAt timestamp instead of removing records
  • GET operations exclude archived records by default
  • Restore endpoints allow unarchiving records

Value Objects Integration

The API properly handles domain value objects:

  • ExternalId - System/Value pairs for external references
  • SalaryRange - Min/Max salary with currency and period
  • LanguageRequirement - Language code with proficiency level

Entity Relationships

  • Companies can have multiple JobPostings
  • JobPostings belong to a Company
  • Proper validation ensures referential integrity

Error Handling

  • 404 responses for non-existent or archived resources
  • 400 responses for invalid requests or validation errors
  • Proper HTTP status codes for all operations

Validation

  • Company existence validation for job posting operations
  • Value object creation validation (ExternalId, SalaryRange, LanguageRequirement)
  • Required field validation through DTOs

Example Usage

Create a User

POST /api/users
Content-Type: application/json

{
  "displayName": "John Doe",
  "type": 0,
  "active": true
}

Create a Company

POST /api/companies
Content-Type: application/json

{
  "name": "Tech Corp",
  "description": "A technology company",
  "location": "San Francisco",
  "employeeCount": 150,
  "externalIds": [
    {
      "system": "LinkedIn",
      "value": "tech-corp"
    }
  ]
}

Create a Job Application

POST /api/jobapplications
Content-Type: application/json

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "jobPostingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 0,
  "notes": "Applied through LinkedIn",
  "applicationSource": "LinkedIn",
  "expectedSalaryMin": 80000,
  "expectedSalaryMax": 100000,
  "salaryCurrency": "USD"
}

Update Application Status

PUT /api/jobapplications/{id}/status
Content-Type: application/json

{
  "status": 3
}

Add Note to Application

POST /api/jobapplications/{id}/notes
Content-Type: application/json

{
  "note": "Had a great phone interview, waiting for next steps"
}

Search Job Postings

GET /api/jobpostings/search?title=developer&location=remote&contractType=0

Filter Job Applications

GET /api/jobapplications?userId=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=1

Get Application Statistics

GET /api/jobapplications/stats?userId=3fa85f64-5717-4562-b3fc-2c963f66afa6

Architecture Notes

Clean Architecture

  • Controllers handle HTTP concerns only
  • Business logic resides in domain entities
  • DTOs provide clean API contracts
  • Mapping extensions handle entity/DTO conversions

Entity Framework Integration

  • In-memory database for development
  • Async operations throughout
  • Proper navigation property loading
  • Configuration through Fluent API

ASP.NET Core Features

  • Controller-based routing
  • Model binding and validation
  • OpenAPI/Swagger integration
  • Dependency injection for DbContext