home / skills / willsigmon / sigstack / api-integration-builder

api-integration-builder skill

safe

/plugins/app-dev/skills/api-integration-builder

This skill helps you create robust API service integrations with protocol, client implementation, caching, DI, and tests.

npx playbooks add skill willsigmon/sigstack --skill api-integration-builder

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

794 B

---
name: API Integration Builder
description: Create new API service integrations for Leavn - REST clients, CloudKit, Bible APIs with proper error handling and caching
allowed-tools: Read, Write, Edit
---

# API Integration Builder

Build API service integrations:

1. **Create protocol** in `Services/{Domain}/`
2. **Implement client**: Async/await, proper errors
3. **Add caching**: CacheManager integration
4. **Register in DI**: DIContainer singleton
5. **Add tests**: Mock for testing

Pattern:
```swift
protocol MyAPIProtocol {
    func fetch() async throws -> Data
}

final class MyAPILive: MyAPIProtocol {
    func fetch() async throws -> Data {
        // URLSession, error handling, caching
    }
}
```

Use when: Adding Bible translation API, CloudKit integration, external service

Overview

This skill helps you create robust API service integrations for Leavn using TypeScript patterns inspired by the project conventions. It guides you through defining a protocol, implementing a live client with async/await and explicit error handling, adding caching via the CacheManager, registering the service as a DIContainer singleton, and adding test-friendly mocks. The result is consistent, testable, and reusable API clients for REST services, CloudKit, and Bible APIs.

How this skill works

You define a clear service interface in Services/{Domain}/ that declares async methods and possible error types. Then implement a live client that performs HTTP requests or CloudKit operations, wraps errors into domain-specific types, and uses CacheManager to cache responses where appropriate. Register the implementation as a singleton in the DI container so consumers get the service via dependency injection. Add unit tests that use a mock implementation to verify behavior and error paths.

When to use it

Adding a new REST API client for external services or microservices.
Integrating CloudKit data sync or read/write operations.
Connecting to Bible translation or scripture content APIs.
When you need consistent error handling and retry/caching behavior.
When you require testable services that can be swapped with mocks.

Best practices

Keep a small, focused protocol per domain that exposes only necessary operations.
Use async/await with explicit thrown errors and map low-level errors to domain types.
Integrate CacheManager for idempotent GET-like operations and define TTLs.
Register the live client as a DIContainer singleton and expose a mock for tests.
Write unit tests covering success, failure, and cache-hit scenarios.

Example use cases

Create a Bible API client that fetches translations, caches verses, and surfaces clear parse errors.
Implement a CloudKit service that handles record creation, conflict resolution, and local caching.
Add a generic REST client for an external service with structured error responses and retry logic.
Build a mock service to run fast unit tests and simulate API error conditions.

FAQ

How do I choose what to cache?

Cache read-only or idempotent responses where freshness can be bounded. Use short TTLs for frequently changing data and longer TTLs for stable content like translations.

What belongs in the protocol vs the implementation?

The protocol should declare behavior (method signatures and expected errors). The implementation contains networking, serialization, caching, and platform-specific details.