# Apiv1 Udtf Endpoint Recipe

> Add, review, or explain Kotlin Spring Boot API endpoints in apiv1 that call Db2 for i table functions. Use when working with UDTFs, TF_* SQL objects, GET endpoints, controllers, services, repositories, row mappers, OpenAPI, JT400, Spring JDBC, or API contract updates under /home/hcantor/Projects/apis/apiv1.

- Skill: `hugocantor/apiv1-udtf-endpoint-recipe` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hugocantor/apiv1-udtf-endpoint-recipe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hugocantor/apiv1-udtf-endpoint-recipe/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: hugocantor (https://skillmd.com/u/hugocantor)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hugocantor/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](examples.md).