api-integration

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

Integrate API for: the invocation request.

## Steps

1. **Identify the API**: Determine the endpoint(s), HTTP method(s), request/response shapes, and authentication requirements for the invocation request.

2. **Define types**: Create typed interfaces for request and response payloads. Co-locate types with the API client module according to the project's conventions.

   ```typescript
   // TypeScript example
   export interface GetItemsParams {
     page: number;
     limit: number;
     status?: 'open' | 'resolved' | 'escalated';
   }

   export interface ItemResponse {
     data: Item[];
     total: number;
     page: number;
   }
   ```

   ```python
   # Python example (Pydantic)
   from pydantic import BaseModel

   class GetItemsParams(BaseModel):
       page: int
       limit: int
       status: str | None = None

   class ItemResponse(BaseModel):
       data: list[Item]
       total: int
       page: int
   ```

3. **Create API client functions**: Place in the project's designated API layer as pure async functions. Use the project's HTTP client.

   ```typescript
   // TypeScript example
   import { httpClient } from '@/lib/httpClient';
   import type { GetItemsParams, ItemResponse } from './types/items';

   export async function getItems(params: GetItemsParams): Promise<ItemResponse> {
     const { data } = await httpClient.get<ItemResponse>('/items', { params });
     return data;
   }

   export async function resolveItem(id: string, resolution: string): Promise<void> {
     await httpClient.post(`/items/${encodeURIComponent(id)}/resolve`, { resolution });
   }
   ```

   ```python
   # Python example (httpx)
   import httpx
   from .schemas import GetItemsParams, ItemResponse

   async def get_items(params: GetItemsParams) -> ItemResponse:
       async with httpx.AsyncClient() as client:
           response = await client.get('/items', params=params.model_dump())
           return ItemResponse.model_validate(response.json())

   async def resolve_item(id: str, resolution: str) -> None:
       async with httpx.AsyncClient() as client:
           await client.post(f'/items/{id}/resolve', json={'resolution': resolution})
   ```

4. **Create data-fetching hooks/functions**: Wrap API calls with the project's caching/state management layer.

   ### Query Pattern (React Query example)
   ```typescript
   import { useQuery } from '@tanstack/react-query';
   import { getItems } from '@/api/items';
   import type { GetItemsParams } from '@/api/types/items';

   export const itemKeys = {
     all: ['items'] as const,
     lists: () => [...itemKeys.all, 'list'] as const,
     list: (params: GetItemsParams) => [...itemKeys.lists(), params] as const,
     details: () => [...itemKeys.all, 'detail'] as const,
     detail: (id: string) => [...itemKeys.details(), id] as const,
   };

   export function useItems(params: GetItemsParams) {
     return useQuery({
       queryKey: itemKeys.list(params),
       queryFn: () => getItems(params),
       staleTime: 5 * 60 * 1000, // 5 minutes
       placeholderData: keepPreviousData,
     });
   }
   ```

   ### Mutation Pattern (React Query example)
   ```typescript
   import { useMutation, useQueryClient } from '@tanstack/react-query';
   import { resolveItem } from '@/api/items';

   export function useResolveItem() {
     const queryClient = useQueryClient();

     return useMutation({
       mutationFn: ({ id, resolution }: { id: string; resolution: string }) =>
         resolveItem(id, resolution),
       onSuccess: () => {
         queryClient.invalidateQueries({ queryKey: itemKeys.all });
       },
     });
   }
   ```

   ### Alternative: Service Layer Pattern (backend or Vue/Angular)
   ```python
   # Python service layer
   from .repository import ItemRepository
   from .schemas import GetItemsParams, ItemResponse

From ajyadav013/claude-kit, MIT.

More from ajyadav013/claude-kit