Apiv1 Udtf Endpoint Recipe

apiv1 UDTF Endpoint Recipe

Purpose

Use this skill when adding, reviewing, or explaining apis/apiv1 Kotlin Spring Boot endpoints backed by Db2 for i table functions under sqlobjects.

Workflow

1. Find the closest existing endpoint in /home/hcantor/Projects/apis/apiv1 before inventing structure.
2. Find the backing SQL object in /home/hcantor/Projects/sqlobjects, usually a TF_* table function.
3. Confirm the endpoint contract:
   • HTTP method and route.
   • Required and optional query parameters.
   • Sort, paging, max rows, and empty-result behavior.
   • Error semantics for invalid input versus host/database failures.
4. Mirror the local Kotlin pattern:
   • Controller handles HTTP binding and response shape.
   • Service handles validation and business-level orchestration.
   • Repository calls FROM TABLE(schema.function(...)).
   • Row mapper converts JDBC rows to DTO/domain objects.
   • Tests cover controller, service, and repository SQL construction where local patterns support it.
5. Update docs/openapi.yaml and any API contract markdown when the route or schema changes.
6. If an Angular client consumes the endpoint, check the matching frontend API/model/mapper files before changing response fields.

SQL Call Rules

• Use parameterized Spring JDBC calls; do not concatenate user input into SQL.
• Keep Db2 for i object names and schema/library assumptions explicit.
• Preserve the table-function result contract unless the user requested a breaking change.
• Treat numeric, packed, date, and blank-padded character fields carefully when mapping to API types.

Output Format

When planning or reviewing, return:

• Endpoint: method and route.
• Backing UDTF: SQL object path and function name.
• Kotlin changes: controller, service, repository, DTO, mapper, tests.
• Contract changes: OpenAPI/docs/frontend impacts.
• Verification: Gradle or targeted tests to run.

Examples

For implementation patterns and prompts, see examples.md.