02 / ЧТО НА САМОМ ДЕЛЕ ДЕЛАЕТ API

API — это договор между программными системами.

На практическом уровне API определяет, как одна application может запросить информацию у другой или попросить её выполнить определённую operation.

Такой contract обычно определяет endpoints, authentication, request format, response format, errors и ожидаемое поведение.

CRM
   │
   │ API REQUEST
   ▼
INTEGRATION SERVICE
   │
   ├────────► ACCOUNTING
   │
   ├────────► INTERNAL PORTAL
   │
   └────────► NOTIFICATION SERVICE

Главная архитектурная идея в том, что employees больше не должны сами выполнять роль integration layer. Software начинает общаться с software напрямую.

03 / MANUAL INTEGRATION

До появления API роль API часто выполняет человек.

Представим customer order, который появился в одной системе. Сотрудник копирует имя customer в spreadsheet, вручную вводит order в другую platform, создаёт invoice, сохраняет PDF и отправляет email следующему сотруднику.

CUSTOMER REQUEST
       ↓
EMPLOYEE
       ↓
COPY DATA
       ↓
SPREADSHEET
       ↓
COPY AGAIN
       ↓
ACCOUNTING SYSTEM
       ↓
CREATE PDF
       ↓
SEND EMAIL
       ↓
UPDATE INTERNAL SYSTEM

При небольшом объёме такой workflow может работать. Но каждый новый manual transition создаёт вероятность delay, duplicate entry, inconsistent data и missing updates.

Этот переход от spreadsheets к специализированным systems мы подробно разбирали в Engineering 001 — Когда Excel перестаёт масштабироваться.

04 / POINT-TO-POINT INTEGRATION

Самая простая integration напрямую соединяет System A и System B.

SYSTEM A ───────── API ─────────► SYSTEM B

Point-to-point integration вполне нормальна, если взаимодействуют всего две системы и workflow остаётся простым.

Сложности появляются, когда каждая application начинает создавать прямые connections со всеми остальными applications.

CRM ───────────────► ACCOUNTING
 │  ╲                    ▲
 │   ╲                   │
 ▼    ╲                  │
PORTAL ───────────────► STORAGE
 │                       ▲
 └──────────────► NOTIFICATIONS

По мере роста количества систем такая architecture становится tightly coupled: изменение одной application неожиданно влияет сразу на несколько integrations.

05 / INTEGRATION LAYER

Integration layer позволяет отделить бизнес-системы друг от друга.

Вместо того чтобы учить каждую application работать со всеми остальными, компания может добавить отдельный integration service, middleware layer или backend, отвечающий за обмен данными.

                 ┌──────────── CRM
                 │
                 ├──────────── ACCOUNTING
                 │
INTEGRATION  ────┼──────────── INTERNAL PORTAL
LAYER            │
                 ├──────────── STORAGE
                 │
                 ├──────────── PAYMENTS
                 │
                 └──────────── NOTIFICATIONS

Такой слой может нормализовывать data, проверять authentication, выполнять retries, записывать audit events и изолировать vendor-specific behavior.

06 / REST APIs

REST остаётся одним из самых распространённых способов business integration.

REST APIs обычно предоставляют resources через HTTP и используют методы GET, POST, PUT, PATCH и DELETE.

GET    /customers/4821
POST   /orders
PATCH  /orders/928/status
DELETE /sessions/183

HTTP RESPONSE
200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
429 Too Many Requests
500 Internal Server Error

Корректные HTTP semantics важны, потому что integration должна предсказуемо понимать, что произошло.

API, который отвечает `200 OK` абсолютно на всё, заставляет consumers придумывать собственные правила, чтобы определить реальный outcome операции.

07 / SYNCHRONOUS COMMUNICATION

Иногда ответ нужен прямо сейчас.

При synchronous communication одна система отправляет request и ждёт response до продолжения workflow.

PORTAL
   │
   │ POST /customer
   ▼
CRM
   │
   │ 201 CREATED
   ▼
PORTAL CONTINUES

Такой подход удобен, когда следующее действие напрямую зависит от результата.

Но caller одновременно становится зависимым от latency и availability downstream service.

08 / ASYNCHRONOUS COMMUNICATION

Не каждая operation должна заставлять пользователя ждать.

Sending notifications, document processing, report generation, synchronization с внешними services или AI analysis могут занимать больше времени, чем должен жить обычный interactive request.

USER ACTION
     ↓
APPLICATION
     ↓
QUEUE / EVENT
     ↓
BACKGROUND WORKER
     ↓
EXTERNAL API
     ↓
RESULT STORED
     ↓
USER NOTIFIED

Asynchronous processing также может улучшить resilience: временный сбой external service не обязан превращаться в мгновенную ошибку для user.

09 / WEBHOOKS

Webhook позволяет внешней системе самой сообщить об изменении.

Без webhook application может постоянно спрашивать provider, появились ли новые данные. Такой подход называется polling.

POLLING

YOUR SYSTEM ──► ANYTHING NEW?
YOUR SYSTEM ──► ANYTHING NEW?
YOUR SYSTEM ──► ANYTHING NEW?


WEBHOOK

EXTERNAL SYSTEM
       │
       │ EVENT OCCURS
       ▼
POST /webhooks/payment-completed
       │
       ▼
YOUR SYSTEM

Webhooks особенно полезны для payments, delivery status, document processing, messaging, identity events и других workflows, где consumer должен быстро реагировать на изменение у provider.

10 / WEBHOOK SECURITY

Webhook endpoint остаётся internet-facing API endpoint.

Сам факт получения POST request не доказывает, что его действительно отправил ожидаемый provider.

Production webhook implementation может требовать signature verification, timestamp validation, replay protection и строгую payload validation.

11 / POLLING

Polling сам по себе не является плохой architecture.

Некоторые providers не поддерживают webhooks. Иногда reconciliation нужен даже при наличии webhook.

В таких случаях polling вполне уместен, если frequency, rate limits, pagination и failure recovery спроектированы осознанно.

Практическая architecture может использовать webhook для быстрого уведомления и scheduled reconciliation для поиска пропущенных событий.

12 / AUTHENTICATION

Программным системам нужна identity так же, как и пользователям.

API authentication отвечает на фундаментальный вопрос: какая application, service или user выполняет request?

В зависимости от provider и risk model могут использоваться API keys, OAuth access tokens, signed requests, service accounts, certificates и другие credentials.

CLIENT
  │
  │ CREDENTIAL / TOKEN
  ▼
API GATEWAY
  │
  ├── AUTHENTICATE
  ├── AUTHORIZE
  ├── RATE LIMIT
  ├── VALIDATE
  │
  ▼
APPLICATION

13 / API KEYS

API key даёт доступ, но не является полноценной security architecture.

API keys удобны для server-to-server integrations, но должны рассматриваться как secrets.

Их нельзя размещать в public frontend JavaScript, хранить в открытом source repository или передавать через URL, где credential может попасть в infrastructure logs.

Для high-value operations authorization должна дополнительно определять, что authenticated identity имеет право делать.

14 / OAUTH 2.0

Delegated access требует другой модели.

OAuth часто используется, когда application должна получить доступ к другому service от имени user или organization, не получая пароль самого пользователя.

USER
 │
 ▼
YOUR APPLICATION
 │
 │ AUTHORIZATION
 ▼
IDENTITY / AUTHORIZATION SERVER
 │
 │ ACCESS TOKEN
 ▼
YOUR APPLICATION
 │
 │ AUTHORIZED API REQUEST
 ▼
RESOURCE API

Token scope, expiration, rotation и secure storage становятся частью integration architecture.

15 / AUTHORIZATION

Authentication отвечает «кто?». Authorization — «что ему разрешено?»

Service может быть правильно authenticated, но при этом не иметь оснований видеть всех customers, менять financial records или выполнять administrative actions.

Least-privilege access уменьшает последствия credential compromise и accidental misuse.

Это особенно важно для internal portals с несколькими employee roles. Подробнее: Engineering 003 — Когда бизнесу нужен внутренний портал?.

16 / IDEMPOTENCY

Что произойдёт, если один и тот же request придёт дважды?

В distributed systems происходят timeouts и неопределённые outcomes.

Client может успешно отправить request, но потерять response. После этого возникает вопрос: безопасно ли повторять operation?

CREATE PAYMENT
      │
      ▼
SERVER PROCESSES PAYMENT
      │
      X  RESPONSE LOST
      │
CLIENT TIMES OUT
      │
      ▼
RETRY?

WITHOUT IDEMPOTENCY:
POSSIBLE DUPLICATE OPERATION

WITH IDEMPOTENCY:
SAME LOGICAL REQUEST → SAME EFFECT

HTTP определяет некоторые methods как idempotent, но бизнес-операциям часто нужна дополнительная application-level защита.

Payment creation, order creation и другие POST-style workflows могут использовать idempotency key или другой transaction identifier.

17 / RETRIES

Если повторять запросы максимально быстро, outage может стать только хуже.

Temporary failures — нормальная часть distributed systems. Networks падают, services перезапускаются, providers throttling traffic, dependencies временно становятся unavailable.

Resilient integration должна различать errors, которые имеет смысл повторить позже, и errors, требующие intervention.

REQUEST
  │
  ▼
TEMPORARY FAILURE
  │
  ▼
WAIT
  │
  ▼
RETRY
  │
  ▼
LONGER WAIT
  │
  ▼
RETRY
  │
  ├── SUCCESS → CONTINUE
  │
  └── FAILURE → DEAD LETTER / ALERT

18 / EXPONENTIAL BACKOFF

Retries должны иметь интервалы и ограничения.

Exponential backoff увеличивает задержку между повторными attempts.

Jitter дополнительно снижает риск ситуации, когда тысячи clients после outage одновременно повторяют request.

19 / RATE LIMITS

External API — не бесконечный ресурс.

Providers часто ограничивают request volume для защиты capacity или в зависимости от service plan.

Integration должна понимать throttling responses и не воспринимать rate limiting как загадочный application failure.

10,000 JOBS
    │
    ▼
WORK QUEUE
    │
    ▼
RATE CONTROLLER
    │
    ├──► API
    ├──► API
    ├──► API
    │
    └── WAIT WHEN THROTTLED

20 / QUEUES

Queue помогает соединять systems, работающие с разной скоростью.

Ваша application может создавать work быстрее, чем external provider способен его обработать.

Queue создаёт buffer между production и consumption этой работы.

Queues особенно полезны для document processing, email delivery, bulk synchronization, AI jobs, imports, exports и других workloads, которым не требуется мгновенное завершение.

21 / DEAD-LETTER QUEUES

Некоторые jobs будут падать снова и снова, сколько их ни retry.

Message может содержать invalid data, ссылаться на удалённый external record или вызывать provider error, который невозможно исправить автоматическим повтором.

Вместо бесконечных retries такие задачи можно переносить в dead-letter queue или отдельное failure storage.

NORMAL QUEUE
    │
    ▼
PROCESS
    │
    ├── SUCCESS ─────► COMPLETE
    │
    └── FAILURE
          │
          ▼
        RETRY
          │
          ▼
     MAX ATTEMPTS
          │
          ▼
DEAD-LETTER QUEUE
          │
          ▼
INSPECT / FIX / REPLAY

Важно не просто сохранить failure. Operator должен видеть достаточно context, чтобы понять причину ошибки и безопасно replay job позже.

22 / EVENT-DRIVEN ARCHITECTURE

Иногда системе лучше публиковать факт, а не напрямую командовать другой системой.

В event-driven architecture одна system сообщает, что событие уже произошло: order создан, payment завершён, document загружен, driver изменил status.

Другие systems подписываются только на те events, которые им действительно нужны.

ORDER SERVICE
      │
      │ ORDER_CREATED
      ▼
EVENT BUS
 ├────────► ACCOUNTING
 ├────────► NOTIFICATIONS
 ├────────► ANALYTICS
 └────────► INTERNAL PORTAL

Такой подход уменьшает direct coupling, но создаёт новые архитектурные вопросы: ordering, duplicate delivery, schema evolution, observability и eventual consistency.

23 / EVENTUAL CONSISTENCY

Distributed systems не обязаны соглашаться мгновенно.

Когда updates распространяются asynchronously, одна system может увидеть изменение раньше другой на миллисекунды или секунды.

Это не обязательно bug. Важно определить, может ли конкретный business workflow выдержать временную inconsistency.

24 / DATA MAPPING

Две системы редко описывают один business object одинаково.

CRM может использовать field customer_id. Другая platform — accountNumber. Internal portal — UUID.

Поэтому integration почти всегда требует mapping layer.

CRM
customer_id
first_name
last_name
phone

       ↓ MAP ↓

INTERNAL PORTAL
customerId
displayName
phoneNumber

       ↓ MAP ↓

ACCOUNTING
accountRef
legalName
contactPhone

Mapping должен также описывать, как преобразуются null values, formats, units, currencies, time zones и enumerations.

25 / CANONICAL DATA MODEL

Общая внутренняя модель уменьшает количество повторных преобразований.

Когда несколько external systems используют разные schemas, integration layer может приводить их к единой canonical internal model.

Тогда downstream services не нужно знать proprietary schema каждого vendor.

VENDOR A ─┐
          │
VENDOR B ─┼──► CANONICAL MODEL ───► BUSINESS LOGIC
          │
VENDOR C ─┘

26 / SCHEMA EVOLUTION

APIs меняются. Integration должна переживать эти изменения.

Добавляются fields. Старые поля становятся deprecated. Enumerations получают новые values. Payloads усложняются.

Consumer не должен предполагать, что каждый response навсегда останется идентичным сегодняшнему примеру.

Defensive parsing, explicit contracts и compatibility testing уменьшают риск, когда API развивается.

27 / API VERSIONING

Breaking changes требуют migration strategy.

API version может находиться в URL, headers или других negotiated contracts.

Конкретный механизм менее важен, чем понятные compatibility expectations.

/api/v1/customers
/api/v2/customers

OLD CLIENT ─────► V1
NEW CLIENT ─────► V2

MIGRATE
VALIDATE
DEPRECATE
REMOVE

Если удалить old version раньше, чем consumers мигрировали, обычный API deployment может превратиться в outage сразу нескольких systems.

28 / PAGINATION

«Дай мне все records» перестаёт работать быстрее, чем кажется.

Большие datasets обычно нужно получать pages или через cursor-based iteration, а не одним огромным response.

Integration должна понимать continuation tokens, page boundaries, ordering guarantees и поведение records, которые меняются прямо во время synchronization.

29 / BULK SYNCHRONIZATION

Initial import и ежедневная synchronization — разные workloads.

При первом подключении system может потребоваться импортировать годы historical records.

После этого обычно синхронизируются только changes.

INITIAL SYNC
1,000,000 RECORDS
      ↓
BATCH / PAGINATION
      ↓
VALIDATION
      ↓
CHECKPOINT


ONGOING SYNC
ONLY CHANGES
      ↓
WEBHOOK / EVENT / POLL
      ↓
UPDATE

30 / CACHING

Не каждый request обязан каждый раз доходить до provider.

Frequently requested data, которое меняется редко, можно cache для уменьшения latency и количества API calls.

Но caching создаёт другой вопрос: насколько stale data допустимы?

Cache lifetime должен следовать business requirements. Product description может обновиться с задержкой. Payment status — возможно, нет.

31 / TIMEOUTS

Каждый external request должен иметь временную границу.

Без timeout один недоступный dependency способен надолго занять resources и распространить failure дальше по application.

USER REQUEST
    │
    ▼
YOUR SERVICE
    │
    ▼
EXTERNAL API
    │
    X NO RESPONSE

WITHOUT TIMEOUT:
WAIT...

WITH TIMEOUT:
FAIL CONTROLLED
RETRY / FALLBACK / QUEUE

32 / CIRCUIT BREAKERS

Если dependency очевидно падает, не нужно продолжать бить его requests.

Circuit breaker временно останавливает обращения к unhealthy downstream service после серии failures.

Provider получает время на recovery, а каждый user request не ждёт одну и ту же предсказуемую ошибку.

CLOSED
REQUESTS FLOW
   │
   ▼
FAILURES EXCEED THRESHOLD
   │
   ▼
OPEN
REQUESTS FAIL FAST
   │
   ▼
WAIT
   │
   ▼
HALF OPEN
TEST REQUEST
   │
   ├── SUCCESS → CLOSED
   └── FAILURE → OPEN

33 / THIRD-PARTY OUTAGES

Ваш application может быть здоровым, даже если integration не работает.

Payment provider, CRM, mapping service или document API могут временно быть недоступны, хотя ваша собственная infrastructure работает нормально.

Хороший UX различает internal failure и delayed external processing.

«Мы получили запрос и синхронизируем его, когда provider снова станет доступен» намного лучше, чем просто потерять request.

34 / RECONCILIATION

Даже event-driven integration должна уметь сверяться с реальностью.

Webhooks могут потеряться. Queue может получить poison message. Credentials могут истечь. Provider может пережить incident.

Reconciliation сравнивает ожидаемый internal state с фактическим state внешней системы и ищет differences.

INTERNAL RECORDS
       │
       ├──── COMPARE ────┐
       │                 │
       ▼                 ▼
EXPECTED STATE      PROVIDER STATE
       │                 │
       └──────┬──────────┘
              ▼
        DIFFERENCES?
          │      │
         NO     YES
          │      │
       COMPLETE  REPAIR / ALERT

35 / OBSERVABILITY

Фраза «integration упала» почти ничего не объясняет.

Production system нужны logs, metrics и alerts, которые показывают, где именно request падает, сколько retries происходит, сколько отвечает provider и растёт ли synchronization backlog.

Полезные metrics могут включать:

• request volume;
• success и error rates;
• provider latency;
• retry count;
• rate-limit events;
• queue depth;
• dead-letter volume;
• webhook verification failures;
• synchronization delay;
• authentication failures.

36 / CORRELATION IDS

Одна business operation может пройти через пять разных services.

Correlation ID позволяет связать logs нескольких components с одной logical transaction.

REQUEST ID: req_82A91

WEB APP
  ↓ req_82A91
API
  ↓ req_82A91
QUEUE
  ↓ req_82A91
WORKER
  ↓ req_82A91
ACCOUNTING PROVIDER

ONE BUSINESS ACTION
ONE TRACEABLE IDENTIFIER

37 / AUDIT LOGS

Operational logs и audit logs решают разные задачи.

Technical logs помогают engineers понять application behavior.

Audit records отвечают на business questions: кто инициировал action, что изменилось и когда это произошло.

Для sensitive workflows могут быть нужны оба типа records.

38 / INPUT VALIDATION

External data нужно считать untrusted data.

Даже authenticated provider может отправить malformed, unexpected или semantically invalid payload.

Integration должна проверять data types, lengths, allowed values, identifiers и business constraints до изменения internal state.

39 / OUTPUT CONTROL

Не отправляйте больше информации, чем integration действительно нужна.

API должен отдавать minimum data, необходимый для конкретного workflow.

Sensitive internal fields не должны автоматически становиться external только потому, что существуют в database.

Особенно это важно для PII, financial records и employee data.

40 / SECRETS MANAGEMENT

Credentials — это infrastructure, а не source code.

API keys, OAuth client secrets, private keys и database credentials должны храниться через appropriate secret-management mechanisms.

Их необходимо отделять от publicly distributed application code.

Rotation procedure тоже важна: secret, который невозможно безопасно заменить, превращается в long-term operational liability.

41 / API GATEWAYS

Gateway может централизовать общие API controls.

В зависимости от architecture API gateway может выполнять routing, authentication, rate limiting, request validation, metrics и другие controls до попадания traffic в application services.

CLIENTS
   │
   ▼
API GATEWAY
 ├── AUTH
 ├── RATE LIMIT
 ├── ROUTING
 ├── LOGGING
 └── POLICY
   │
   ├────────► SERVICE A
   ├────────► SERVICE B
   └────────► SERVICE C

Gateway полезен, но он не исправит плохо спроектированную authorization или inconsistent business rules внутри самих services.

42 / INTEGRATION TESTING

Mock responses полезны. Реальное поведение provider всё равно отличается.

Unit tests проверяют transformation logic. Integration tests — contracts. Sandbox — authentication и provider-specific behavior.

Но production integration всё равно нужна observability, потому что реальные datasets, throttling и outages могут показать то, чего test environment не воспроизводит.

43 / SANDBOX ENVIRONMENTS

Используйте test environment provider, если она существует.

Payment providers, identity platforms и enterprise APIs часто дают sandbox или отдельный test tenant.

Это снижает риск случайно создать real charges, customers, notifications или production data во время разработки.

44 / CONTRACT TESTING

API может быть online и всё равно сломать вашу integration.

Contract testing проверяет structure и behavior, которые одна system ожидает от другой.

Если provider изменил важное response field или ваш internal API изменил required property, contract tests могут обнаружить incompatibility до production deployment.

45 / LEGACY SYSTEM INTEGRATION

Старое software тоже может участвовать в modern API architecture.

У legacy systems часто нет современного API. Adapter может создать controlled boundary вокруг old database, service или application.

LEGACY SYSTEM
      │
      ▼
ADAPTER / ANTI-CORRUPTION LAYER
      │
      ▼
MODERN API
      │
      ├──► INTERNAL PORTAL
      ├──► MOBILE APP
      ├──► AUTOMATION
      └──► AI SERVICES

Этот подход напрямую связан с Engineering 004 — Legacy Software Modernization.

46 / ACCOUNTING INTEGRATION

Financial integrations требуют особенно ясного data ownership.

Internal portal может рассчитывать operational values, а accounting software оставаться authoritative system для invoices, payments и financial reporting.

OPERATIONS
    │
    ▼
INTERNAL PORTAL
    │
    │ APPROVED FINANCIAL EVENT
    ▼
ACCOUNTING API
    │
    ▼
INVOICE / PAYMENT RECORD
    │
    ▼
REFERENCE STORED INTERNALLY

Architecture должна определять, какая system владеет financial truth и как corrections распространяются обратно.

47 / CRM INTEGRATION

CRM и operational portal могут владеть разными частями customer lifecycle.

CRM может оставаться authoritative для leads, opportunities и sales activity, а custom operational system управлять fulfillment после запуска сделки.

Integration не даёт sales и operations создавать две независимые версии customer data.

48 / DOCUMENT INTEGRATION

File — это не только upload. Нужны metadata и lifecycle.

Storage provider может хранить binary object, а internal system — document type, owner, expiration, workflow state и access permissions.

BUSINESS RECORD
      │
      ├── DOCUMENT TYPE
      ├── STATUS
      ├── OWNER
      ├── EXPIRATION
      │
      ▼
STORAGE API
      │
      ▼
FILE OBJECT

49 / TRANSPORTATION INTEGRATION

Transportation workflows часто зависят сразу от нескольких systems.

Dispatch, drivers, vehicle records, documents, settlements, claims, accounting и customer communication могут постоянно обмениваться data.

Кейс M&N Soft Driver Portal показывает, как specialized transportation workflows можно централизовать, сохранив integrations с external services.

Также мы разрабатываем custom transportation software.

50 / AI AGENTS & APIs

AI agent становится operational, когда получает доступ к tools.

Language model сам по себе может анализировать text. Но AI agent становится гораздо более значимым, когда умеет читать customer data, создавать requests, искать documents или вызывать business APIs.

USER
  │
  ▼
AI AGENT
  │
  ├──► SEARCH API
  ├──► CRM API
  ├──► DOCUMENT API
  └──► INTERNAL ACTION API
            │
            ▼
      BUSINESS SYSTEM

Но вместе с этим появляется важное security requirement: agent не должен получать permissions шире, чем требует workflow.

Tool access, human approval и auditability становятся частью AI architecture.

Подробнее: AI integration для бизнеса.

51 / HUMAN APPROVAL

Automation не требует исключить человека из каждого решения.

Low-risk actions могут выполняться автоматически, а high-impact operations — только после approval.

AUTOMATION / AI
      │
      ▼
PROPOSE ACTION
      │
      ├── LOW RISK ─────► EXECUTE
      │
      └── HIGH RISK
             │
             ▼
        HUMAN REVIEW
             │
        ┌────┴────┐
        ▼         ▼
      APPROVE   REJECT

52 / BUILD VS BUY

Строить собственную integration infrastructure или использовать automation platform?

Integration platforms и automation tools могут быть отличным решением, если workflow укладывается в их connectors и operational requirements.

Custom integration становится особенно полезной, когда business logic proprietary, security requirements специфичны, data volume значителен или нужна глубокая control над поведением integration.

Используйте самую простую architecture, которая надёжно выполняет business requirement.

53 / COMMON FAILURE MODES

Десять способов превратить API integration в operational problem.

• Нет timeout для external requests.
• Infinite retries.
• Нет idempotency для duplicate-sensitive operations.
• Secrets находятся прямо в source code.
• Webhook signatures не проверяются.
• Нет reconciliation после пропущенных events.
• Никто не видит рост queue backlog.
• Одна system владеет data, а другая незаметно их меняет.
• Breaking schema changes происходят без versioning.
• Нет процесса replay failed jobs.

54 / DECISION MATRIX

Какой communication pattern подходит конкретному requirement?

55 / INTEGRATION CHECKLIST

Перед соединением двух systems ответьте на эти вопросы.

• Какая system владеет каждым типом data?
• Communication synchronous или asynchronous?
• Как caller проходит authentication?
• Какая minimum authorization ему нужна?
• Что произойдёт при duplicate request?
• Какие errors можно retry?
• Какой timeout?
• Какие rate limits существуют?
• Как восстанавливаются failed jobs?
• Как проверяются webhooks?
• Как выполняется reconciliation?
• Как обрабатываются schema changes?
• Какие metrics должны запускать alerts?
• Как выполняется secret rotation?
• Как integration будет тестироваться?

56 / СВЯЗАННЫЕ ENGINEERING МАТЕРИАЛЫ

API integration — только один слой большой business architecture.

Engineering 001 — Когда Excel перестаёт масштабироваться →

Engineering 002 — Стоимость custom software в США →

Engineering 003 — Когда бизнесу нужен internal portal? →

Engineering 004 — Legacy Software Modernization →

Разработка Custom Software →

Автоматизация бизнес-процессов →

57 / FAQ

Частые вопросы про API integration.

Что такое API integration?

API integration — это соединение независимых software systems через определённые application interfaces, чтобы они автоматически обменивались data или запускали operations.

Чем API отличается от webhook?

API request обычно инициирует consumer. Webhook чаще инициирует provider в момент возникновения event.

REST API безопасен?

Сам REST не делает API безопасным или небезопасным. Security зависит от transport protection, authentication, authorization, validation, secret handling, access control и application design.

Нужно ли retry failed requests?

Некоторые failures стоит повторять, некоторые — нет. Retry behavior зависит от semantics операции, idempotency и рекомендаций provider.

Что такое idempotency key?

Это identifier, по которому server распознаёт повторную попытку одной logical operation и не создаёт duplicate effect.

Когда нужен message queue?

Queue полезна, когда work может выполняться asynchronously, systems работают с разной скоростью или temporary outage не должен приводить к потере work.

Нужно ли каждой system напрямую соединяться со всеми остальными?

Нет. По мере роста ecosystem dedicated integration layer может уменьшить coupling и централизовать reliability concerns.

Можно ли дать modern API старому legacy application?

Часто да. Adapter или abstraction layer может открыть selected legacy capabilities и скрыть implementation details от новых applications.

Можно ли безопасно позволить AI agent вызывать business APIs?

Можно, но tool access должен иметь строгую authorization, validation, auditability и human approval, если последствия action существенны.

Сколько стоит API integration?

Стоимость зависит от количества systems, качества API, authentication, data complexity, workflow rules, reliability requirements и testing. Более широкий market context есть в Engineering 002 — Стоимость custom software в США.

58 / ПЕРВИЧНЫЕ ИСТОЧНИКИ И TECHNICAL REFERENCES

Стандарты и security guidance для API architecture.

Эти primary technical resources дают дополнительный контекст по HTTP semantics, API security, OAuth и secure software design.

IETF / RFC Editor — RFC 9110: HTTP Semantics ↗

IETF / RFC Editor — RFC 6749: OAuth 2.0 Authorization Framework ↗

OWASP — REST Security Cheat Sheet ↗

OWASP — API Security Project ↗

NIST SP 800-228 — Guidelines for API Protection ↗

NIST SP 800-218 — Secure Software Development Framework ↗

NIST SP 800-207 — Zero Trust Architecture ↗

59 / ПОДХОД M&N SOFT

Хорошая integration убирает невидимую ручную работу.

Цель API integration не в том, чтобы соединить максимальное количество systems.

Цель — создать dependable information flow, чтобы employees не тратили время на перенос одних и тех же данных между разными software products.

В зависимости от workflow это может быть простой REST connection, webhook, queue, integration service, custom internal portal или более крупная automation architecture.

Integration действительно работает, когда бизнес может полагаться на неё даже тогда, когда network, provider или отдельный request дают сбой.

ОБСУДИТЬ INTEGRATION

Нужно, чтобы ваши business systems наконец работали вместе?

M&N Soft разрабатывает API integrations, internal business portals, workflow automation, transportation software, AI integrations и custom software вокруг реальных operational processes.

Можно начать с карты systems, которые компания уже использует, определить source of truth для каждого типа data и найти места, где automation может убрать manual work.