Integration Architecture

API Integration Working Skill

Choose the right protocol, define the contract, handle auth and versioning, and design error behavior so the integration works under real load and real failure conditions.

What this skill is for

This skill helps you decide which protocol to use for a given integration need, define the API contract with version and error semantics, design authentication and rate-limiting, and document the integration so it can be operated without guessing.

When to use this skill

A new system needs to exchange data with SAP or another enterprise system.
You are replacing a legacy point-to-point integration with a standardized API.
An existing API is breaking consumers due to unannounced schema changes.
You need to choose between REST, OData, SOAP, or IDoc for a specific flow.
Authentication credentials are expiring and the rotation process is undefined.
Consumers report timeouts or rate-limit errors under production load.

Real work situations

Situation 1: New CRM needs customer data from SAP S/4

The CRM team requests "an API" for customer master. The integration team must decide whether to expose OData from S/4, build a middleware REST API, or use an existing IDoc. The wrong choice creates coupling, performance issues, or data lag.

Situation 2: Legacy SOAP service failing under load

A SOAP service built five years ago is timing out during month-end. The team wants to modernize but does not know whether to migrate to REST, OData, or an event-driven pattern. The decision affects consumer rework, middleware config, and monitoring.

Situation 3: API contract mismatch causing order creation failures

A downstream system sends orders via REST API. After a middleware update, the JSON schema changes slightly. Orders fail with 400 errors. There is no versioning strategy, so both sides blame each other.

Inputs required

Integration requirement: data entities, direction, frequency, volume.
Existing interface inventory (to avoid duplication).
System landscape: SAP version, middleware, consumer platforms.
Authentication mechanisms available (basic, OAuth, certificate, SAP principal).
SLA requirements: availability, latency, throughput.
Non-functional requirements: security, compliance, payload limits.
Consumer capabilities: what protocols and auth they support.
Failure history of similar integrations (optional but valuable).

Questions to ask

What is the data volume per call and per day?
Does the consumer need the data in real time, near real time, or batch?
Who owns the API contract, and who approves changes to it?
What happens to the business process when the API is unavailable for 1 minute? 1 hour?
How should the consumer behave on timeout, 500 error, 400 error, 429 error?
What is the maximum acceptable payload size?
How are breaking changes communicated to consumers?
Is the consumer internal or external, trusted or untrusted?

Working method

Map the need to a pattern. Document the business process, data entities, direction, frequency, and consumer count. Classify as read, write, or bidirectional.
Choose the protocol. Compare REST, OData, SOAP, IDoc, and file based on consumer needs, SAP capabilities, and team skills. Record the decision in an ADR.
Define the contract. Specify endpoint, methods, request/response schema, error schema, content type, and charset. Include example payloads.
Design authentication. Choose mechanism, define credential lifecycle (creation, rotation, revocation), and document how consumers obtain access.
Define SLA and limits. State availability target, max latency, rate limit, and payload size limit. Document what happens when limits are exceeded.
Design error handling. Define error codes, retryability, and consumer behavior per status code. Link to the Integration Error Handling skill.
Plan versioning. Choose URL versioning, header versioning, or content negotiation. Define deprecation policy and communication lead time.
Document operational details. Write runbook entries for: how to check health, how to diagnose failure, how to rotate credentials, who to page.
Validate with consumer test. Run a structured test with the consumer using realistic data and failure injection. Fix contract gaps before go-live.

Decision rules

If the consumer is a user-facing application needing real-time data, use REST or OData.
If the integration is bulk transactional with SAP as the source or target, evaluate IDoc or OData batch before REST.
If the external system is a SaaS platform with complex query needs, use OData.
If authentication uses tokens, define a rotation process with a grace period; never hardcode credentials.
If the payload exceeds 1 MB, use an asynchronous pattern or chunked transfer; do not force synchronous.
If there are more than 5 consumers for the same data, prefer a middleware layer or event bus over direct API calls.
If the consumer is external or untrusted, enforce schema validation and rate limiting at the entry point.
If backward compatibility cannot be maintained, increment the version and support the old version for at least 90 days.

Deliverables

API Contract Document — Endpoint, schema, examples, error codes, version.
Architecture Decision Record — Why this protocol was chosen. Link to ADR template.
Interface Ownership Matrix entry — Owners, SLA, status. Link to Interface Ownership Matrix template.
Operational Runbook excerpt — Health check, failure diagnosis, credential rotation.

Templates

API Contract Brief

---
artifact: API Contract Brief
id: API-001
status: draft | reviewed | approved
---

## Interface


## Endpoint


## Request schema


## Response schema


## Example payload


## Error codes
| Code | Condition | Retryable | Consumer action |
|------|-----------|-----------|-----------------|
| 400  | Schema validation failed | No | Fix payload |
| 401  | Authentication expired | Yes | Refresh token and retry |
| 429  | Rate limit exceeded | Yes | Backoff and retry |
| 500  | Internal server error | Yes | Retry with backoff |
| 503  | Service unavailable | Yes | Retry with backoff |

## Version


## Rate limit


## Payload limit


## Auth mechanism


## Owner


## SLA

Quality checklist

Contract has a version number and a deprecation policy.
Every error code states whether the consumer should retry.
Authentication mechanism is documented with rotation steps.
Rate limits and payload size limits are specified.
Backward compatibility rule is stated explicitly.
At least one realistic example payload is included.
Operational owner is named.
Health check endpoint is defined.

Common mistakes

Mistake: Skipping error code design. Consequence: Consumers guess whether to retry, causing duplicate data or thundering herds.
Mistake: Hardcoding endpoint URLs or credentials in consumer code. Consequence: Every environment change or credential rotation requires a code deployment.
Mistake: No versioning strategy. Consequence: Schema changes break all consumers simultaneously.
Mistake: Ignoring payload size limits until production. Consequence: Timeouts and memory issues under real data volumes.
Mistake: Designing the API for a single consumer without considering future consumers. Consequence: The API becomes a point-to-point integration with a misleading name.

Agent instructions

Gather context first: Collect integration requirements, existing interface inventory, system landscape, and NFRs before proposing a protocol.
Separate facts from assumptions: Do not assume the consumer supports OAuth, JSON, or webhooks. Verify their capabilities explicitly.
Produce artifacts: Generate an API Contract Brief and an Architecture Decision Record. Do not stop at a recommendation.
Avoid generic language: Do not write "REST is modern and flexible." Write "Use OData if the consumer needs filtered queries over SAP entities."
Handle missing information: If SLA or auth requirements are missing, list them as open questions and block the design until answered.
Link to Atlas diagnostics: If the integration involves SAP, reference outbound processing and inbound processing diagnostics for failure patterns.

Related skills

Event-Driven Architecture — When synchronous APIs are not the right pattern.
Interface Ownership — Assign owners before finalizing the contract.
Integration Error Handling — Design retry and failure behavior.
Integration Observability — Monitor the API after go-live.
Architecture Decision Record — Record the protocol choice.

Related Atlas pages

API Contracts — Conceptual foundation for contract design.
REST vs OData vs SOAP vs IDoc vs Events — Protocol comparison.
Synchronous vs Asynchronous Integration — When to avoid APIs.
Integration Pattern Decision Matrix — Structured protocol selection.

Verification status and limitations

This skill is a public working interpretation of API integration practice. It is not official SAP, OpenAPI, or vendor documentation. SAP-specific guidance is aligned with S/4HANA OData and common IDoc patterns but may need adaptation for custom landscapes or older releases. Always validate protocol choices against the specific SAP release and middleware in use.