---

type: skill name: Api Design description: Design RESTful APIs following best practices skillSlug: api-design phases: [P, R] generated: 2026-01-20 status: filled scaffoldVersion: "2.0.0"

API Design Skill

When to Use

Use this skill when:

• Designing CLI interfaces
• Planning function signatures
• Creating export formats
• Designing data structures

CLI API Design

Command Structure

Pattern from project:

Copyscript.py [command] [options] [arguments]

Examples:

Copy# Simple command
python indexer.py

# Command with arguments
python search.py "termo de busca"

# Command with options
python search.py "termo" --category anexo --export results.csv

# Command with flags
python search.py --list-categories

Function API Design

Pattern: Function Signatures

Copy# Good: Clear parameters with defaults
def search(query, category=None, contract_number=None, export_csv=None):
    """Busca documentos no banco de dados."""

Argument Parsing Pattern

Use argparse for CLI:

Copyparser = argparse.ArgumentParser(description='Busca documentos indexados')
parser.add_argument('query', nargs='?', help='Termo de busca')
parser.add_argument('--category', '-c', help='Filtrar por categoria')

Data Structure Design

Return Values

Pattern: Dictionary for complex data

Copyreturn {
    "category": category,
    "contract_number": contract_number,
    "document_type": document_type,
    "document_number": document_number
}

Metadata Format

Pattern: JSON metadata

Copymetadata = {
    "size": stat.st_size,
    "size_mb": round(stat.st_size / (1024 * 1024), 2),
    "modified": datetime.datetime.fromtimestamp(stat.st_mtime).isoformat()
}
metadata_json = json.dumps(metadata, ensure_ascii=False)

Export Format Design

CSV Export

Pattern: Consistent column names

Copydata.append({
    "Arquivo": filename,
    "Categoria": category,
    "Tipo": doc_type,
    "Contrato": contract_number or "",
    "Trecho": fragment,
    "Caminho": filepath
})

API Versioning

Current approach: CLI-based (no versioning needed)

• Functions can evolve
• CLI commands stable
• Export formats consistent

Design Principles

1. Consistency: Similar functions have similar signatures
2. Clarity: Parameter names are self-documenting
3. Flexibility: Optional parameters for common use cases
4. Error Handling: Clear error messages in Portuguese

Examples from Codebase

Good API Design

Copydef search(query, category=None, contract_number=None, export_csv=None):
    """Busca documentos no banco de dados."""
    # Clear parameters
    # Optional filters
    # Export option

Good CLI Design

Copypython search.py "termo" --category anexo --contract TNE_JU_COM_0002-13 --export results.csv

Checklist

• Clear function signatures
• Consistent naming
• Optional parameters have defaults
• Error handling documented
• Examples provided
• Export formats consistent