API Integration and Partner Portals in 2026
Zubin Gala
Principal Mobile App Engineer, Unico Connect
In this article
- Quick Answer
- Key Takeaways
- The Four Integration Patterns
- What a Partner Portal Actually Needs
- API Design Decisions That Age Well
- Authentication, Briefly and Practically
- When Not to Build This
- How Unico Connect Builds Integration Layers and Portals
- Where These Numbers Come From
- Frequently Asked Questions
- Conclusion
Most B2B software spends its life talking to other software. The interesting engineering is rarely the screens, it is the layer where an order in one system becomes a shipment in another, and where a distributor sees their own pricing without anyone emailing a spreadsheet. That layer is where projects quietly succeed or fail.
This guide covers the four integration patterns worth knowing, what a partner portal actually requires beyond a login, and the API design decisions that still look sensible in three years.
Quick Answer
There are four integration patterns and the choice is driven by how many systems you connect. Point to point works for two or three systems and becomes unmaintainable beyond that. An integration layer, sometimes called a middle layer, centralises the mapping and is the right default for most companies. A partner portal exposes a controlled slice of your systems to distributors or customers. Event driven integration decouples systems that must not wait for each other. Unico Connect builds all four, most often the integration layer and partner portal together, and the current specification to document any of it is OpenAPI 3.2.0, published in September 2025.
Key Takeaways
- The number of connected systems, not their type, determines the pattern. Point to point connections grow at roughly the square of the system count, which is why the third integration is cheap and the eighth is a rewrite.
- A partner portal is an access control problem before it is a user interface problem. Every query must be scoped to the partner making it, enforced on the server, and every write must be audited.
- OpenAPI 3.2.0 is the current specification, published on 19 September 2025. Many guides and generators still target 3.1, so check what your tooling actually emits before standardising on it.
- Idempotency is the single highest value design decision in any integration. Without it, every network timeout risks a duplicate order, and retries become dangerous rather than routine.
- Integration work is mostly data reconciliation. Two systems will disagree about what a customer or a price is, and resolving that is the actual project.
The Four Integration Patterns
The four API integration patterns, when each fits and what it costs you
| Pattern | Best when | Strength | Where it breaks |
|---|---|---|---|
| Point to point | Two or three systems, stable and unlikely to grow | Fastest to ship, nothing extra to operate | Connections grow with the square of the system count |
| Integration layer, middle layer | Four or more systems, or mapping logic worth owning | One place to change, one place to monitor | Becomes a single point of failure without proper operations |
| Partner portal | Distributors or customers need controlled self service | Removes email and phone work from your team | Authorisation must be server side and role aware from day one |
| Event driven | Systems must not block on each other, or volume is spiky | Decoupled, absorbs load, replayable | Harder to debug, and ordering plus duplicates need real thought |
Which should you choose
Pattern guidance reflects how we build. OpenAPI 3.2.0 was published 19 September 2025 by the OpenAPI Initiative.
What a Partner Portal Actually Needs
A distributor or customer portal looks like a small application and behaves like a security boundary. Five requirements decide whether it holds up.
Scoped access, enforced server side. Every request must resolve to the partner making it, and the filter has to live on the server. A portal that fetches everything and hides rows in the interface is not a portal, it is a data breach with a nice layout. This is the most common serious defect we find in existing portals.
Roles that match how partners work. A distributor is not one person. There is someone who places orders, someone who reconciles invoices, and someone who only needs to see stock. Model those roles at the start, because retrofitting authorisation into a portal that assumed one user type is close to a rewrite.
Self service that removes a human. The portal earns its cost by absorbing work someone currently does by email. Order status, invoice history, stock levels, returns. If every meaningful action still ends in a phone call, you have built a viewer rather than a portal.
Search built for the catalogue you actually have. Industrial and technical catalogues are searched by specification and part code, not by marketing name. Generic text search over a technical catalogue is the reason partners give up and call the sales desk.
An audit trail. Who changed what, when, and on whose behalf. This matters the first time a partner disputes an order, which is a certainty rather than a risk.
API Design Decisions That Age Well
Six decisions account for most of the difference between an integration that lasts and one that gets rebuilt.
Step one, make writes idempotent. Accept a client supplied key on every state changing request and return the original result if the same key arrives twice. This turns a timeout from a possible duplicate order into a safe retry, and it is the difference between an integration you can operate and one you have to babysit.
POST /v1/orders
Idempotency-Key: 8f3c1d2e-4b7a-4c19-9f0e-2a6b5c8d1e37
Content-Type: application/json
Step two, version from the first release. Put the version in the path and treat it as a contract. The cost of /v1/ on day one is nothing. The cost of adding versioning once three partners depend on unversioned endpoints is a coordinated migration you do not control.
Step three, document with OpenAPI 3.2.0 and generate from it. A specification that is written by hand alongside the code will drift within a quarter. Generate the documentation, the client libraries, and ideally the request validation from one specification file that lives in the repository. Version 3.2.0 was published on 19 September 2025, so confirm your generators support it rather than assuming.
Step four, paginate with cursors, not page numbers. Offset pagination breaks quietly when the underlying data changes between requests, which for an active order table is constantly. Cursors are marginally more work and do not silently skip records.
Step five, decide what a failure looks like before you ship. One error shape, meaningful status codes, and a machine readable code alongside the human message. Partners integrate against your errors as much as your successes.
Step six, publish rate limits and return them in headers. A partner who can see their remaining quota will back off. A partner who cannot will retry in a loop and take down the endpoint for everyone.
Authentication, Briefly and Practically
For server to server integration, use OAuth client credentials or signed API keys, scope them narrowly, and make rotation possible without downtime by supporting two live credentials at once. For partner portal users, use ordinary session authentication with roles.
The failure to avoid is a single long lived key with full access, shared by email, that nobody can rotate because it is embedded in a partner system somebody else maintains. That key will outlive the project.
When Not to Build This
Not every integration deserves custom engineering. If you are connecting well known SaaS products with standard objects and no unusual logic, an integration platform will do it faster and cheaper than we can, and you should use one. Custom work earns its place when the mapping is genuinely proprietary, when volume makes per operation pricing painful, when the data cannot leave your infrastructure, or when the integration is a product feature rather than internal plumbing.
For choosing the API style itself, see our comparison of GraphQL and REST. If the consumer is an AI agent rather than another system, MCP versus direct API integrations covers that decision.
How Unico Connect Builds Integration Layers and Portals
We build these in strict TypeScript on Node.js, with NestJS for structured platforms and Fastify or Express for lighter services, automated tests and continuous integration from the first commit, and senior engineer review on every pull request. Services deploy into cloud accounts you own, and you keep the code and the intellectual property throughout, under our ISO/IEC 27001:2022 and ISO 9001:2015 certified practice.
Recent work includes Ebco, a React distributor portal with technical SKU search integrated into existing operational systems, which made order processing 35 percent faster. For a diversified manufacturer we built a sales and finance platform with a distributor self service portal that replaced three fragmented systems and cut reconciliation errors by 30 percent. For a multi outlet jeweller we built a purchase history middle layer that unified invoices, returns, and exchanges across every outlet.
See Node.js development for the backend practice, custom software development for full platform builds, or hire Node.js developers to add API capacity to your own team.
I have spent years on the consuming side of other people APIs, and two things separate the good ones. Writes are idempotent, so a timeout on a bad mobile connection is a safe retry rather than a duplicate order. And the version is in the path, so an upgrade is my decision rather than a surprise. Everything else I can work around. Those two I cannot.
Zubin Gala, Principal Mobile App Engineer, Unico Connect
Where These Numbers Come From
The OpenAPI Specification version and its 19 September 2025 publication date come from the official specification published at spec.openapis.org. The client outcomes are from our own case studies, linked above. The pattern guidance reflects how we build rather than a published benchmark, and the connection growth point is simply the arithmetic of connecting every system to every other one.
Frequently Asked Questions
What is the difference between point to point and an integration layer?
Point to point means each system talks directly to each other system, so the connection count grows roughly with the square of the number of systems. An integration layer puts one component in the middle that each system talks to instead, so adding a system means one new connection rather than several. Point to point is fine for two or three systems and becomes unmaintainable beyond that.
What is the current OpenAPI version in 2026?
OpenAPI Specification 3.2.0, published on 19 September 2025. It is worth checking that your documentation renderers, client generators, and validation middleware actually support 3.2.0, because a good deal of tooling still targets 3.1 and will silently ignore newer constructs.
Do I need an API gateway?
If you expose APIs to partners, something has to handle authentication, rate limiting, and observability, and a gateway is the usual answer. For a handful of internal services, gateway features are often better handled in the application and the extra component is a cost without a benefit. Add it when you have external consumers or more services than one team can track.
How do you stop duplicate orders when a request times out?
Idempotency keys. The client sends a unique key with each write, the server records it, and if the same key arrives again it returns the original result instead of creating a second order. Without this, the honest answer is that you cannot safely retry, and every timeout becomes a support conversation.
What makes a partner portal different from a normal web application?
Authorisation. Every query has to be scoped to the partner making the request and enforced on the server, not filtered in the browser. Add role separation within each partner organisation and a full audit trail of who did what on whose behalf, and most of the remaining work is ordinary application development.
Should we use an integration platform instead of building?
Often yes. If you are connecting mainstream SaaS products with standard objects and simple logic, an integration platform is faster and cheaper. Build custom when the mapping is proprietary, when volume makes per operation pricing expensive, when data cannot leave your infrastructure, or when the integration is itself a feature customers use.
How long does an integration project take?
The interface is rarely the constraint. The delay is almost always reconciling data definitions between systems that disagree about what a customer, a product, or a price is. A focused integration between two well documented systems is a matter of weeks. Anything involving a legacy system with no specification takes as long as discovery takes.
Conclusion
Integration quality comes down to where the mapping lives and whether writes are safe to retry. Centralise the mapping, make every state changing request idempotent, version from the first release, document with OpenAPI 3.2.0 and generate from that document, and scope every partner query on the server. Do those five things and the integration stops being the fragile part of the system.
For the API style decision see GraphQL vs REST, for agent facing integration see MCP vs direct API integrations, and to have this built or reviewed see Node.js development or contact us.
