api

name	api
description	Use for tasks that define, repair, validate, or preserve external interface contracts: REST or FastAPI endpoints, Pydantic models, JSON Schema, OpenAI tool/function schemas, ChatML or SFT JSONL formats, request batching, streaming callbacks, and client-visible compatibility behavior.

API and Interface Contracts

When To Use

Use this skill when the artifact is an interface boundary. The boundary can be an HTTP endpoint, a schema file, a function-calling tool definition, a JSONL data format, a streaming callback contract, or a public client behavior.

First Pass

1. Identify the consumer: tests, client code, model trainer, router, batcher, or evaluator.
2. Extract the contract from examples and tests: field names, types, required fields, defaults, ordering, error shape, and serialization format.
3. Separate public compatibility from internal implementation. Internal code can change; public fields and behavior need deliberate migration.
4. Build validation around both accepted and rejected cases.

Implementation Patterns

REST and HTTP Contracts

HTTP method semantics:

• GET — safe and idempotent; reads only, no side effects.
• POST — creates a resource or triggers a non-idempotent action.
• PUT — replaces the full resource at a known URL; idempotent.
• PATCH — partial update of an existing resource.
• DELETE — removes a resource; idempotent (repeat returns 404 or 204).

Status codes — pick the narrowest accurate one:

• 200 OK (success with body), 201 Created (resource created, return Location), 204 No Content (success, empty body).
• 400 Bad Request (malformed), 401 Unauthorized (missing/invalid auth), 404 Not Found, 409 Conflict (state conflict, e.g. duplicate key), 422 Unprocessable Entity (well-formed but semantically invalid — typical Pydantic/FastAPI validation failure).
• 500 Internal Server Error for unexpected server faults; do not leak tracebacks in the body.

Error response shape — keep it stable across endpoints:

{"error": {"code": "invalid_field", "message": "top_k must be >= 1", "details": {"field": "top_k"}}}

Versioning: prefer URL path (/v1/resource) for hard breaks; use a header (API-Version: 2026-04-30) for additive evolution. Never silently change response shape within a published version.

OpenAI Tool Schema

Map source parameter types to JSON Schema and keep required/default behavior explicit.

TYPE_MAP = {
    "str": {"type": "string"},
    "int": {"type": "integer"},
    "float": {"type": "number"},
    "bool": {"type": "boolean"},
    "list[str]": {"type": "array", "items": {"type": "string"}},
    "datetime": {"type": "string", "format": "date-time"},
}

def tool_schema(desc):
    properties, required = {}, []
    for p in desc["parameters"]:
        properties[p["name"]] = {
            **TYPE_MAP[p["type"]],
            "description": p.get("description", ""),
        }
        if "default" not in p:
            required.append(p["name"])
    return {
        "name": desc["name"],
        "description": desc["description"],
        "parameters": {
            "type": "object",
            "properties": properties,
            "required": required,
        },
    }

Validate test calls by unknown tool, missing required argument, and type mismatch. Return descriptive errors, not generic failure flags.

ChatML and SFT JSONL

For fine-tuning datasets, each line must be a standalone JSON object. Preserve message role order, deterministic split policy, IDs, and escaping.

import json

with open("train.jsonl", "w") as f:
    for row in rows:
        obj = {"messages": row["messages"]}
        f.write(json.dumps(obj, ensure_ascii=False) + "\n")

Re-read the JSONL after writing and assert every line parses independently.

FastAPI and Pydantic Contracts

Use typed request/response models for boundary validation. Keep response models stable and prefer additive changes. For compatibility tasks, inspect client tests before renaming fields or changing defaults.

from pydantic import BaseModel, Field

class Request(BaseModel):
    query: str = Field(min_length=1)
    top_k: int = Field(default=10, ge=1, le=100)

Batching and Streaming

For inference batching, preserve request IDs and callback ordering. Record each accepted request, dispatch batch, result, timeout, and error. A good execution log lets tests prove that batching did not drop or reorder client-visible results.

Validation

• Validate schemas against representative valid and invalid calls.
• Re-read generated JSON, JSONL, or manifests with a strict parser.
• Exercise endpoint/client behavior at the public boundary.
• Confirm error messages name the failing field or reason.
• Check deterministic ordering for schemas, logs, and dataset splits.

Common Failures

• Hiding constraints in prose instead of schema.
• Accepting malformed calls silently.
• Changing public field names while tests or clients still depend on them.
• Producing JSONL that looks right as a whole file but has invalid individual lines.
• Preserving happy paths while breaking error compatibility.