---
name: api-integration
description: Work with REST APIs — curl, authentication, webhooks, error handling, integration patterns.
version: 1.0.0
license: MIT
metadata:
  hermes:
    tags: [api, rest, curl, webhooks, integration, http]
    category: devops
    requires_toolsets: [terminal]
---

# API Integration

Work with REST APIs, webhooks, and HTTP integrations. Test endpoints, handle auth, parse responses, and set up integrations.

## When to Use

- Call a REST API (GET, POST, PUT, DELETE)
- Debug API responses and errors
- Set up webhook receivers or senders
- Handle authentication (Bearer, Basic, API keys)
- Parse JSON/XML responses
- Set up API monitoring

## curl Quick Reference

```bash
# GET with headers
curl -s https://api.example.com/endpoint -H "Authorization: Bearer TOKEN"

# POST with JSON body
curl -s -X POST https://api.example.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# POST with file
curl -s -X POST https://api.example.com/upload \
  -F "file=@./document.pdf"

# Follow redirects, show response headers
curl -sL -D - https://api.example.com

# Timeout and retry
curl -s --connect-timeout 5 --max-time 30 https://api.example.com

# Save response to file
curl -s -o response.json https://api.example.com/data
```

## Common Auth Patterns

```bash
# Bearer token
Authorization: Bearer sk-xxxx

# Basic auth
curl -u username:password https://api.example.com

# API key in header
curl -H "X-API-Key: xxxxx" https://api.example.com

# API key in query
curl "https://api.example.com?api_key=xxxxx"
```

## Error Handling

```bash
# Show HTTP status code only
curl -s -o /dev/null -w "%{http_code}" https://api.example.com

# Full verbose output for debugging
curl -v https://api.example.com

# Check if endpoint is reachable
curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 https://api.example.com/health
```

## Webhooks

- Webhook receivers typically need a public URL (use Railway or Contabo with nginx)
- Verify payload signature if provided
- Return 200 quickly, process async
- Log incoming webhooks for debugging

## Pitfalls

| Problem | Fix |
|---------|-----|
| CORS error in browser | Add CORS headers on server or use proxy |
| 401 Unauthorized | Token expired or wrong auth scheme |
| 429 Too Many Requests | Add rate limiting / backoff |
| Connection refused | Service not running or wrong port |
| SSL cert error | Use `-k` for testing (not for production) |
| JSON parse error | Validate JSON with `jq .` or `python -m json.tool` |

## Verification
```bash
# Check HTTP status
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health
# Should be 200

# Check response body
curl -s https://api.example.com/health | jq .
```
