Create a POST Applicant API

[bradenwingfield]

Description

Create a POST Applicant API endpoint that creates a new applicant in the database with their basic information and application details.

Technical Details

1. Create the Action Function

Create a new function in packages/internal-models/src/db/actions/Applicant.ts that will:

• Take a CreateApplicantRequest as input and return an ApplicantResponse
• Connect to the database using dbConnect()
• Create a new applicant with the provided data
• Set default values for status and statusUpdatedAt
• Return the created applicant

Reference Examples:

• See packages/internal-models/src/db/actions/Applicant.ts for other applicant actions like getApplicants() and deleteApplicant()
• See apps/form-builder/src/server/actions/forms.ts for the createForm() function as a similar example

2. Create the API Route

Create a new file at apps/applicant-tracking/src/app/api/applicants/route.ts that will:

• Import necessary dependencies from internal-models and next/server
• Create a POST function that handles the HTTP request
• Parse and validate the request body using Zod
• Call the createApplicant action function
• Return appropriate HTTP responses with status codes

Reference Examples:

• See apps/applicant-tracking/src/app/api/applicants/[applicantId]/route.ts for the DELETE endpoint implementation
• See apps/form-builder/src/app/api/forms/route.ts for the POST endpoint implementation
• See apps/form-builder/src/app/api/forms/[formId]/formSubmissions/route.ts for a more complex POST implementation

Teachables

Action Function

The action function is responsible for:

• Database operations (connecting and creating records)
• Business logic (setting default values)
• Data transformation (converting between request and response types)
• Error handling for database operations

API Route

The API route is responsible for:

• HTTP request handling (parsing body, headers)
• Input validation using Zod schemas
• Calling the appropriate action function
• Returning HTTP responses with proper status codes
• Error handling for HTTP-level issues

Data Flow

1. Client sends HTTP POST request with applicant data
2. API route receives request and validates data
3. If valid, calls action function
4. Action function connects to database and creates record
5. Action function returns created applicant
6. API route returns HTTP response with applicant ID

Error Handling

• API level: Handles HTTP errors (400 for invalid input, 500 for server errors)
• Action level: Handles database errors
• Both levels: Provide meaningful error messages

Testing Steps

1. Make a POST api call using postman with the url localhost:3000/api/applicants
2. Set the Content-Type header to application/json
3. Include a JSON body with the required fields:

{
  "firstName": "John",
  "lastName": "Doe",
  "netid": "jdoe",
  "term": "Fall 2024",
  "application": "507f1f77bcf86cd799439011" // Form submission ID
}

4. Verify the response:

   • Status code should be 201 for successful creation
   • Response body should contain the new applicant's ID

5. Test error cases:

   • Missing required fields (should return 400)
   • Invalid term format (should return 400)
   • Invalid application ID (should return 400)
   • Database connection error (should return 500)

6. Verify the applicant was created in the database with:

   • All provided information matches the request
   • Status is set to 'Pending Review'
   • statusUpdatedAt is set to current timestamp

Additional Resources

Schema and Model References

• See packages/internal-models/src/types/applicant.ts for the Zod schema definitions
• See packages/internal-models/src/db/models/Applicant.ts for the Mongoose model definition

API Service References

• See apps/applicant-tracking/src/services/api/applicant.ts for how the API is consumed by the frontend
• See apps/applicant-tracking/src/utils/constants/urls.ts for API endpoint URL definitions