# API Developer

> Use when designing, building, or integrating APIs and system integrations — REST API design, GraphQL schemas, gRPC services, webhook handlers, API gateways, third-party API integration, or ETL pipelines between systems. Trigger phrases: "API design", "integration", "webhook", "API gateway", "OpenAPI spec", "GraphQL schema", "gRPC proto", "third-party API", "data sync", "ETL pipeline", "middleware integration", "iPaaS", "API versioning", "rate limiting".

- Skill: `barastrong/api-developer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add barastrong/api-developer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/barastrong/api-developer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: barastrong (https://skillmd.com/u/barastrong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/barastrong/api-developer

---


# API Developer / Integration Engineer

## Role Summary

An API Developer / Integration Engineer designs, builds, and maintains APIs
and system-to-system integrations. The role focuses on clean contract design,
reliability, backward compatibility, and seamless data flow between internal
and external systems.

## Core Responsibilities

- Design API contracts (OpenAPI, GraphQL SDL, Protocol Buffers)
- Implement API endpoints with proper versioning and deprecation strategy
- Build integrations with third-party services (payment, CRM, ERP, etc.)
- Implement webhook producers and consumers with retry/idempotency
- Design and manage API gateways (rate limiting, auth, routing)
- Build data transformation and mapping layers between systems
- Monitor API health, latency, error rates, and usage metrics
- Write comprehensive API documentation and developer guides

## Standard Workflow

1. **Requirements** — identify consumers, data contracts, SLAs, rate limits.
2. **Contract Design** — OpenAPI/GraphQL/Proto spec first; review with
   consumers before implementation.
3. **Implementation** — build endpoints, transformation logic, error handling.
4. **Auth & Security** — API keys, OAuth2, JWT validation, IP allowlisting,
   input sanitization.
5. **Testing** — contract tests (Pact), integration tests, load tests,
   chaos tests for third-party failures.
6. **Documentation** — auto-generated docs, code samples, SDKs if needed.
7. **Deployment** — API gateway config, versioning, canary rollout,
   monitoring dashboards.

## Technology Stack

| Layer | Tools |
|-------|-------|
| API Styles | REST, GraphQL, gRPC, WebSocket, Server-Sent Events |
| Specs | OpenAPI 3.x, GraphQL SDL, Protocol Buffers |
| Gateways | Kong, AWS API Gateway, Nginx, Envoy, Traefik |
| Integration | Zapier, n8n, Apache Camel, MuleSoft, custom middleware |
| Auth | OAuth2, API keys, JWT, mTLS |
| Testing | Pact (contract), Postman/Newman, k6, Artillery |
| Monitoring | Datadog, New Relic, Prometheus, API analytics |
| Documentation | Swagger UI, Redoc, Stoplight, GraphQL Playground |

## Best Practices

- Contract-first design: spec before code, review with consumers.
- Semantic versioning for APIs; support N-1 version minimum.
- Idempotency keys for all non-GET operations.
- Circuit breaker pattern for third-party calls (Polly, resilience4j, opossum).
- Exponential backoff with jitter for retries.
- Pagination: cursor-based preferred over offset for large datasets.
- Consistent error format across all endpoints (RFC 7807).
- Rate limiting with clear headers (X-RateLimit-Limit, Remaining, Reset).
- Webhook delivery: signed payloads (HMAC), retry with exponential backoff,
  dead letter queue for failures.

## Anti-Patterns to Avoid

- Breaking changes without versioning.
- Exposing internal data models directly as API response schemas.
- No timeout on outbound HTTP calls to third-party APIs.
- Synchronous chains of API calls without fallback/circuit breaker.
- API documentation that diverges from actual implementation.
- Ignoring backward compatibility — always assume old consumers exist.

## References

- `references/api-versioning-guide.md` — versioning strategies and migration
- `references/integration-patterns.md` — EIP patterns for system integration
- `references/webhook-design.md` — webhook reliability patterns

## Expected Output Format

1. API contract/spec (OpenAPI, GraphQL SDL, or Proto file)
2. Implementation with tests (contract + integration)
3. Documentation (auto-generated + usage examples)
4. Monitoring/alerting configuration for new endpoints