Расскажи про свой опыт проектирования интеграции REST

REST API интеграция: мой опыт проектирования

REST API интеграции с внешними системами — это одна из самых common задач BA. Это critical потому что API это interface между вашей системой и чужими. Расскажу мой опыт.

Первая интеграция (наивный подход)

В fintech проекте нужна была интеграция с платежной системой (Stripe). Я просто взял их документацию и написал требования как она описана.

Результат: Разработчик кодил, интеграция работала... иногда. Иногда платежи зависали, иногда возвращались неправильные статусы.

Проблемы:

1. Я не спросил "А что если Stripe API down?" (нет fallback)
2. Я не спросил "Что если payment в PENDING state 24 часа?" (нет retry logic)
3. Я не спросил "Что если webhook от Stripe не приходит?" (нет reconciliation)
4. Я не определил retry policy
5. Я не определил timeout

Урок: Просто copy-paste API documentation это плохо.

Правильный подход (marketplace интеграция)

Позже я спроектировал интеграцию с правильным способом.

Шаг 1: Понять что нужно (requirements gathering)

Перед тем как писать требования, я задал вопросы:

1. Scope: Какие операции нужны?

   • Создать платеж
   • Получить статус
   • Отменить платеж
   • Получить историю

2. Reliability: Что если сервер down?

   • Система должна retry до 3 раз
   • Exponential backoff: 1 second, 2 seconds, 5 seconds
   • Если все fails: escalate human для review

3. Data consistency: Что если мы отправили платеж но не получили ответ?

   • Implement idempotency (same request twice = one payment)
   • Store transaction ID
   • Reconcile каждый hour (compare our records с их records)

4. Monitoring: Как мы узнаем что integration broke?

   • Log all API calls
   • Alert если response time > 5 seconds
   • Alert если success rate < 95%

Шаг 2: Анализ их API (reverse requirements)

Я read их API documentation и спросил критичные вопросы:

1. Rate limiting: Сколько requests в минуту?

   • Ответ: 100 requests per minute
   • Я спросил: Что если мы превышаем? Они return 429 (Too Many Requests)
   • Requirement: Implement queue чтобы не превышать rate limit

2. Authentication: Как authenticate?

   • Ответ: Bearer token
   • Я спросил: Как долго token valid?
   • Ответ: 24 часа
   • Requirement: Refresh token за hour до expiry

3. Error codes: Какие возможные ошибки?

   • 401: Unauthorized (token expired)
   • 402: Payment required (insufficient funds)
   • 429: Rate limit
   • 503: Service unavailable
   • Requirement: Handle каждый error differently

4. Webhook: Отправляют ли они callbacks?

   • Ответ: Да, payment status updates via webhook
   • Я спросил: Гарантия delivery? Они: At-least-once (может быть дубликаты)
   • Requirement: Idempotent webhook handler (дубликаты OK)

Шаг 3: Спроектировать интеграцию

Архитектура:

Our app → Queue (Redis) → Integration service → External API
                            ↓
                        Webhook receiver (для updates)
                            ↓
                        Database (store transaction)

Flow:

1. User делает платеж
2. Мы создаем transaction record (status = PENDING)
3. Мы кладем request в queue
4. Integration service достает из queue, отправляет API
5. Если success: update status на PROCESSING
6. Когда webhook приходит: update status на COMPLETED/FAILED
7. Каждый hour: reconcile (сравни наши records с их records)

Шаг 4: Документировать requirements

Я документировал детальные требования:

API Call requirements:

POST /api/v1/payments
Request:
{
  "amount": "100.00",    (string, not number - for precision)
  "currency": "USD",
  "idempotency_key": "txn_123abc"   (for idempotency)
}

Response (on success):
{
  "id": "charge_xyz",
  "status": "succeeded",  
  "amount": "100.00",
  "timestamp": "2024-03-26T10:30:00Z"
}

Error responses:
- 401: token expired → refresh and retry
- 429: rate limit → queue and retry later
- 402: insufficient funds → user-facing error
- 503: service down → queue and retry in 5 minutes

Retry policy requirements:

Max retries: 3
Backoff: exponential (1s, 2s, 5s)
Do NOT retry on: 401, 402, 4xx client errors
DO retry on: 429, 5xx, timeouts

Webhook requirements:

We listen at: POST /webhooks/payment
Webhook may come multiple times for same event
Treat as idempotent: if we already processed this event_id, ignore
Must respond with 200 within 5 seconds
If we fail: they retry for 24 hours

Monitoring requirements:

Log: все API calls (timestamp, request, response, duration)
Alert если:
- Average response time > 3 seconds
- Success rate < 95%
- Reconciliation finds mismatch

Шаг 5: Validation

Я провел требования к:

1. Разработчику: "Может ли это реализовать за 2 недели? Есть ли risks?"
2. QA: "Как мы тестируем retry logic? Как мы simulate failures?"
3. Tech lead: "Нужно ли queue system (Redis) или можем обойтись?"

Пример requirements для интеграции

## Payment Integration Requirements

### Overview
System must integrate с банком (XYZ Bank) для process payments.

### Happy Path
1. User initiates payment of 100 USD
2. System creates transaction record (PENDING status)
3. System sends API request to XYZ Bank
4. XYZ Bank returns charge_id + status SUCCEEDED
5. System updates transaction (COMPLETED status)
6. XYZ Bank sends webhook confirmation
7. System reconciles (confirms payment)
8. User sees "Payment successful"

### Error Handling
If API returns 429 (rate limit):
- Queue request
- Retry after 2 minutes
- Max 3 attempts
- If all fail: alert operations team

If API returns 503 (service down):
- Queue request
- Retry with exponential backoff
- Max 10 attempts over 1 hour

If webhook doesn't arrive within 24 hours:
- Reconciliation job queries XYZ Bank API
- If XYZ shows payment SUCCEEDED but we have PENDING:
  - Update our record
  - Send receipt to user
- If XYZ shows FAILED:
  - Update our record
  - Refund if money was charged

### Non-functional requirements
API response time: < 3 seconds (P95)
Success rate: > 99%
Retry backoff: exponential (max 30 minutes between retries)
Idempotency: same request (same idempotency_key) = same result

Ошибки которые я видел (и как их избежать)

Ошибка 1: No rate limiting handling

• Разработчик игнорировал rate limit requirement
• В production: system got blocked by API
• Fix: added queue system
• Lesson: enforce requirement через code review

Ошибка 2: No idempotency

• Если request retry: payment happened twice
• Customers потеряли деньги
• Fix: added idempotency_key
• Lesson: explain WHY идемпотентность важна

Ошибка 3: No webhook reconciliation

• Webhook потерялся somewhere
• Payment в их system но у нас PENDING
• Customer didn't get receipt
• Fix: added reconciliation job
• Lesson: document failure scenarios

Best practices для REST интеграции

1. Read их documentation fully перед писать requirements
2. Test against sandbox перед production
3. Implement idempotency для all requests
4. Handle all error codes не только happy path
5. Implement retry logic с exponential backoff
6. Monitor integration - log everything
7. Reconcile regularly - compare vs theirs
8. Document decisions - почему выбрали эту retry policy

Tools которые я используюю

• Postman: test API calls manually
• Documentation: word all requirements clearly
• Code review: ensure requirements implemented correctly
• Monitoring: datadog/prometheus для tracking API health

Вывод

Dobra REST интеграция это не просто "call their API". Это:

• Understand их API deeply
• Spécify requirements для reliability, idempotency, retry, monitoring
• Test against edge cases
• Monitor production closely
• Have fallback plan if integration fails

Best integration я делал: CRM system с Salesforce. Я потратил 2 недели на requirements (вместо usual 2 дней). Результат: zero production issues, smooth data sync, happy customers.

Это prove что time spent на правильной specification of integration this saves многом больше time позже на debugging production issues.