interview-demo-code/.cursor/prompts/api-generation.md

Prompts for API generation

Creating a new API endpoint

Create a new API endpoint [ENDPOINT_NAME] for [DESCRIPTION]:

1. Handler in [HANDLER_PATH]:
   - Method handle() accepts Request
   - Validate input data
   - Use a Service for business logic
   - Return JsonResponse with correct structure
   - Handle errors with logging

2. Service in [SERVICE_PATH]:
   - Business logic
   - Work with Model
   - Data validation
   - Exception handling

3. Model in [MODEL_PATH] (if needed):
   - Methods for working with the database
   - Use Query Builder
   - Proper method typing

4. Route in routes.php:
   - Add a route with the correct name

5. Migration (if a new table is needed):
   - Create a migration in database/migrations/
   - Use fixed acmeshop_ prefix for the table
   - Add indexes where necessary

Follow the project MVC-L architecture and reuse existing patterns.

Creating a CRUD API

Create a full CRUD API for entity [ENTITY_NAME]:

1. Handler with methods:
   - list() – list with pagination and filtering
   - get() – fetch a single record
   - create() – create
   - update() – update
   - delete() – delete

2. Service with business logic for all operations

3. Model with methods:
   - findAll() – list
   - findById() – by ID
   - create() – create
   - update() – update
   - delete() – delete

4. DTO for data validation

5. Migration for table [TABLE_NAME]

6. Routes for all endpoints

Use server-side pagination, filtering, and sorting for list().

Creating an Admin API endpoint

Create an Admin API endpoint [ENDPOINT_NAME] in bastion/Handlers/:

1. Handler in bastion/Handlers/[HANDLER_NAME].php:
   - Use Request to read parameters
   - Validate data
   - Call a Service for business logic
   - Return JsonResponse with structure { data: { data: [...], totalRecords: ... } }
   - Handle errors

2. Service in bastion/Services/ (if needed):
   - Admin-specific business logic
   - Work with Models

3. Route in bastion/routes.php

4. Frontend component (if UI is needed):
   - Vue component in frontend/admin/src/views/
   - Use PrimeVue components
   - Server-side pagination/filtering
   - Error handling with toast notifications

Follow existing project patterns.

Creating a Frontend API client

Create a function for working with API endpoint [ENDPOINT_NAME]:

1. In frontend/[admin|spa]/src/utils/http.js:
   - api[Method] function to call the endpoint
   - Proper error handling
   - Return a structured response

2. Usage:
   - Import in components
   - Handle loading states
   - Show toast notifications on errors

Follow existing patterns in http.js.

Creating a migration

Create a migration for table [TABLE_NAME]:

1. File: database/migrations/[TIMESTAMP]_[DESCRIPTION].php
2. Use fixed acmeshop_ prefix for the table
3. Add all required fields with correct types
4. Add indexes for frequently used fields
5. Use utf8mb4_unicode_ci collation
6. Use InnoDB engine
7. Add created_at and updated_at timestamps
8. Do not create foreign keys (use indexes only)

Follow the structure of existing migrations.