The first time I had to connect two business systems that were never really designed to work together, the problem did not look like an API problem at all. It looked like a personal problem. Every morning, someone on the operations team exported a CSV from the order management system, cleaned up a few fields in Excel, and imported the file into the warehouse system. Then they did it again in the afternoon. The process had been running for about two years, and because the person doing it knew exactly what to click, nobody had much reason to question it.
Until the order volume changed. During a promotional campaign, the company started receiving orders much faster than the existing process could handle. An order placed at eleven in the morning might not reach the warehouse until the afternoon import. By then, inventory could have changed, a product could have gone out of stock, or a customer could have modified the order.
I remember looking at the process and thinking that the software itself was not necessarily broken. The real problem was the gap between the two systems. I spent a good part of the next phase mapping out exactly what happened to an order from the moment it was placed to the moment the warehouse received it. Once I followed the data instead of just looking at the screens, the problem became much easier to understand. Both systems already had APIs.
What they did not have was an integration using those APIs properly. That distinction has stayed with me because API and integration are often used as though they mean the same thing. They do not. An API is an interface. An integration is the working connection and logic built around that interface. Once you understand that difference, a lot of confusing conversations about software architecture become much easier.
What an API Actually Is
An API, or Application Programming Interface, is a defined way for one piece of software to communicate with another. That sounds abstract until you look at what happens in an actual system. Suppose an order management platform has an endpoint for retrieving an order. The API defines how another system should ask for that order, what authentication it needs, what information can be included in the request, and what the response will look like.
The API is essentially the agreement between the two pieces of software. I find it useful to think about an API as a controlled doorway. The software on the other side decides what is allowed through that doorway. It might allow another application to retrieve orders, create customers, update inventory, or change an order status. It might also refuse certain requests completely.
That last part matters. An API is not simply a pipe through which you can push anything you want. A properly designed API has rules. Those rules cover endpoints, request methods, authentication, required fields, response formats, permissions, and often rate limits as well.
For example, a REST API might allow a system to send a "GET" request to retrieve an order, while a "POST" request might create a new record. The application consuming the API has to follow the contract exposed by the system.
During integration work, I have found that understanding this contract is one of the first things worth doing properly. It is tempting to jump straight into writing code because the connection looks straightforward. Then you discover halfway through the project that one endpoint returns a product ID while another system expects a SKU, or that an apparently simple field is actually optional in one system and mandatory in the other. Those details are where integration projects usually become real engineering projects.
So, What Is an Integration?
An integration is what makes separate systems work together for a particular business purpose. It can use APIs, but an API by itself is not an integration. In the order and warehouse project, the APIs were already there. The integration was the layer we built to use them.
That layer had several responsibilities. It had to notice when a new order appeared, retrieve the complete order information, translate the data into the format expected by the warehouse system, send it across, record what had happened, and deal with failures. None of those individual steps sounds especially dramatic.
Put them together, though, and you have a system that has to keep two independent applications synchronized without losing or duplicating information. That is an integration.
It is also why integrations can become difficult surprisingly quickly. Moving one simple record from System A to System B is easy. Keeping thousands of records synchronized while dealing with network failures, expired credentials, duplicate requests, changed APIs, missing data, and unexpected responses is a very different problem.
There are integrations that still use files, too. Some companies exchange CSV or XML files on a schedule. Others use EDI, particularly where established business partners already rely on standardized electronic documents. So it would be inaccurate to say that every integration is an API integration. But for modern applications, APIs are one of the most common ways of building that connection.
The Difference Between an API and an API Integration
This is where I usually slow the conversation down, because the terminology can make the two sound much closer than they actually are. An API belongs to the system exposing it. An integration belongs to the solution connecting systems for a particular purpose. Imagine a commerce platform exposes an API that gives access to customer and order information. That same API could be used by several completely different applications.
One company might use it to send orders to a fulfillment platform
Another might use it to feed an analytics system
A third might use it to synchronize customers with a CRM
The API has not changed. The integration has
When I worked through the order-to-warehouse connection, the API gave us access to the data. It did not tell us what our business should do with that data. That logic had to be designed. We had to decide what event should trigger the process, which fields mattered, how records should be matched, what should happen when inventory was unavailable, and what the system should do if the warehouse API stopped responding.
That is the part people often underestimate when they hear, “They have an API, so integration should be easy.”Having an API is a prerequisite in many cases. It is not the integration itself.
What an API Integration Looks Like in Real Work
The most useful way I can explain this is through the actual flow I worked with the order management system exposed a REST API. The warehouse system had its own API, but the two systems used different data structures. When a customer placed an order, the order management system generated an event through a webhook.
The integration received that event and used the order management API to retrieve the complete order. We then transformed the information into the structure required by the warehouse system. That transformation step was more important than it looked on paper.
The order system might call something a "product_id", while the warehouse system might identify the same item by SKU. One system could represent an address in several separate fields while another expected a different structure. Dates, quantities, status values, and customer information all had to be mapped correctly. After the transformation, the integration sent the fulfillment request to the warehouse API.
We also stored the relationship between the order ID in the first system and the fulfillment ID in the second. That became important later when the warehouse sent status information back. I remember spending time on those mappings because they were exactly the sort of detail that looked insignificant during the initial discussion but became critical once real data started moving through the system. The API provided the access. The integration provided the intelligence.
REST, SOAP, and GraphQL: Why the API Type Matters
Not every API behaves in the same way, and that difference affects integration design. REST is probably the API style developers encounter most often in modern web applications. It typically works through HTTP methods such as GET, POST, PUT, and DELETE, with JSON commonly used for the exchanged data. From an integration perspective, REST can be relatively straightforward because the resources and operations are usually easy to understand.
SOAP is different. It is more rigid and commonly uses XML-based messages and formal service contracts. I still come across SOAP when dealing with older enterprise systems, financial platforms, and other environments where those established contracts remain important.
That rigidity can be frustrating when you are trying to build a modern integration around an older system, but it also has advantages. The contract is explicit, and organizations that have depended on these systems for years often value that predictability.
GraphQL takes another approach. Instead of simply calling a fixed endpoint and receiving a predefined response, the client can request the particular fields it needs. That can reduce unnecessary data transfer, especially when an application only needs a small part of a larger object. The important thing from an integration perspective is not which technology is fashionable. It is understanding what the connected system actually exposes.
I have seen projects get unnecessarily complicated because someone chose a technology based on what sounded modern rather than what the existing systems could support cleanly. The better question is usually: What does the business need, and what is the most maintainable way to connect the systems involved?
Authentication and Security in API Integration
Getting two systems to communicate is only half the job. They also need to trust each other appropriately. Every production API integration needs some form of authentication and authorization. The exact mechanism depends on the API. API keys are relatively simple. A system receives a secret key and includes it with requests. They are easy to understand and implement, but they need careful handling and rotation.
OAuth 2.0 is more involved but is widely used when applications need delegated access and expiring tokens. Access tokens can be limited by scope and renewed through refresh mechanisms without repeatedly asking the user to authenticate. JWTs, or JSON Web Tokens, are another common mechanism for carrying signed claims about an authenticated request.
The technical mechanism is important, but what I pay particular attention to during integration work is what happens after the credentials are issued.
Credentials expire
Keys get rotated
Permissions change
Tokens get revoked
An integration that works perfectly for six months can suddenly stop moving data because somebody changed a credential and nobody updated the connection. That is why authentication cannot be treated as a box that gets checked during development and forgotten.
Secrets also need to be kept out of source code, access needs to be limited to what the integration actually requires, and logs need to be designed so they help diagnose problems without exposing sensitive information. Those decisions are not separate from integration design. They are part of it.
The Part That Usually Hurts: Error Handling
The first serious failure in the order-to-warehouse integration taught me something I now look for almost immediately in integration projects. The warehouse API went offline during a maintenance period. Our integration sent a request, received a "503 Service Unavailable" response, and did not handle the situation properly. Seventeen orders were affected.
The next morning, the fulfillment team found orders in the order management system that had never reached the warehouse. Technically, neither system had lost the orders. The problem was in the connection between them. That incident changed the way I looked at the happy path. It is easy to design an integration around the assumption that the API will respond successfully every time. Real systems do not behave that way.
Networks fail
Servers restart
APIs reach rate limits
Credentials expire
Data arrives in an unexpected format
A third-party service can be unavailable for twenty minutes without warning
A resilient integration needs to expect those situations
Retry logic is useful for temporary failures. If an API times out or briefly returns a service-unavailable response, the integration can retry rather than immediately treating the operation as permanently failed. Exponential backoff is particularly useful because it prevents an already struggling system from being hit repeatedly in rapid succession. Then there is the dead-letter queue.
Once I started looking at integrations from an operational perspective, this became one of the features I considered essential for important data flows. If a request cannot be processed after the allowed retries, it should not simply disappear. It should be preserved somewhere that a person or another process can inspect and reprocess it.
And there is another issue that can be even more dangerous: duplicates.
Suppose the warehouse receives an order successfully, but the connection fails before the integration receives confirmation. The integration may assume the request failed and send it again without idempotency, the warehouse could end up with two fulfillment requests for one customer order.
Idempotency keys help solve that problem by giving the operation a unique identifier that the receiving system can recognize if the same request arrives again. That kind of failure handling is not exciting to demonstrate in a sales presentation. It is incredibly valuable at two in the morning when something goes wrong.
API Integration vs. EDI: They Are Not Really Competitors
The same company also had another kind of integration problem. Some of its larger retail partners were using EDI to exchange purchase orders, acknowledgments, and shipping information. At one point, we discussed whether those connections should also be moved to APIs. After looking at the actual business relationships, the answer was no.
The partners were already using established EDI processes. Their systems expected standardized documents such as purchase orders and advance ship notices, and changing that arrangement would have required changes on both sides. That experience made the API-versus-EDI debate much less theoretical for me.
API integration is particularly useful when systems need flexible, often real-time communication and both sides can support the required interface. EDI remains valuable when businesses need standardized document exchange between established trading partners. The choice is therefore not simply about which technology is newer.
Inside the company, real-time API integrations made sense between the order, warehouse, inventory, and notification systems because the company controlled both ends with external retail partners, EDI remained the sensible option because the business relationship and operational requirements were built around it.
Sometimes the best architecture is not replacing the old thing. It is knowing where the old thing still makes sense.
When an Integration Platform Is Worth Considering
Building integrations yourself is perfectly reasonable when there are only a few of them. If I have two or three systems, a capable development team, well-documented APIs, and straightforward requirements, writing the integration directly can give me more control without introducing another platform that the team now has to learn and maintain.
The calculation changes when the number of integrations starts growing. Each connection brings authentication, monitoring, retries, transformations, logging, error handling, version changes, and maintenance. Five integrations can be manageable. Twenty integrations can become an ecosystem.
That is where an integration platform, or iPaaS, can start making practical sense. These platforms often provide pre-built connectors, centralized monitoring, authentication management, transformation tools, and other shared infrastructure. The attraction is not that the platform magically makes integrations easy. It is that the team does not have to rebuild the same supporting infrastructure for every connection.
I would still be careful about adopting one simply because it appears on a technology comparison chart. There is a cost to learning, operating, and depending on an integration platform. The platform also needs to support the APIs and workflows the business actually uses for a small integration footprint, custom code may be simpler.
For a large and constantly changing integration landscape, shared infrastructure can save a considerable amount of engineering effort.
What I Learned From Building the Connection
Looking back at that first project, the biggest lesson was not about REST, webhooks, OAuth, or JSON. It was about separating the layers of the problem. The order management system already knew how to manage orders. The warehouse system already knew how to manage fulfillment. Neither system needed to be rebuilt. What was missing was a reliable mechanism for allowing those systems to work together. Once I started tracing the data instead of looking only at the applications themselves, the architecture became much clearer.
The same thinking has helped me with later integration work. When something breaks, I first want to know which layer actually failed.
Did the API reject the request?
Did authentication fail?
Did the integration transform the data incorrectly?
Did the receiving system become unavailable?
Did the request succeed but the response get lost?
Was the same transaction processed twice?
Those are very different problems, even though someone in the business might simply say, “The integration is broken.”
Conclusion
An API and an integration are closely related, but they are not interchangeable terms. An API defines how software can communicate with a system. An integration uses that interface, along with business rules, transformation logic, authentication, error handling, monitoring, and state management, to make two systems accomplish something together. That distinction sounds small until you have to troubleshoot a production system.
In the project I described, the APIs were already available. The missing piece was the integration that could use them reliably. And when the warehouse API later went offline, the API itself was not the problem. The weakness was in how our integration responded to the failure. That is why I now think about API work in terms of the entire flow rather than the connection alone.
The real question is not, “Does this system have an API?”
It is, “What happens to the data after we use it?”
That is where the engineering begins.
FAQs
Is an API the same thing as an integration?
No. An API is an interface exposed by a software system. An integration is the connection and logic built to make separate systems work together. A useful way to picture it is this: the API provides the doorway, while the integration decides when to use the doorway, what to send through it, what to do with the response, and what happens when something goes wrong.
Do all integrations use APIs?
No integrations can also use file transfers, databases, message queues, EDI, and other mechanisms. API-based integration is particularly common for modern applications because it can support real-time and event-driven communication. I would not choose an API simply because it is newer. The right approach depends on the systems involved and the business requirement.
What usually causes an API integration to fail?
There is no single failure point. Credentials can expire. An API can become unavailable. A system can reject a request because its format changed. Rate limits can be reached. Network connections can time out. A data transformation can also introduce errors even when both APIs are working perfectly. The integrations I trust most are designed with those failures in mind rather than assuming every request will succeed.
When should a business use an integration platform?
It depends mainly on the scale and complexity of the integration environment. For a couple of straightforward connections, custom code may be easier to maintain. When a company has many integrations, frequent new connections, different authentication requirements, and a growing need for centralized monitoring, an iPaaS can reduce the amount of repeated infrastructure the development team has to maintain. The platform should solve a real maintenance problem. Otherwise, it can simply become another system to manage.
Is EDI outdated compared with API integration?
Not necessarily. EDI and APIs solve somewhat different problems. APIs are often a better fit for real-time communication between systems that can interact directly. EDI remains widely useful for standardized business-document exchange between established trading partners. In some environments, using both is the most practical architecture.
What should I look for when designing an API integration?
I would start with the business workflow rather than the API documentation. Map what event starts the process, what data needs to move, how records are matched between systems, what happens when data is missing, how authentication will work, what happens when the receiving system is unavailable, how retries are handled, and how failed transactions will be found later. Only after those questions are clear does the actual API implementation become straightforward. That is also where I have found the difference between an integration that merely works in a demo and one that can survive real business traffic.
