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, and the interesting engineering rarely sits in the screens. Projects quietly succeed or fail in the layer underneath, where an order in one system becomes a shipment in another and a distributor sees their own pricing without anyone emailing a spreadsheet.
We start with the four integration patterns worth knowing and when each fits, then cover what a partner portal requires beyond a login and the API design decisions that still look sensible in three years.
Quick Answer
There are four integration patterns, and which one fits depends on how many systems you connect, whether partners need access, and whether those systems can wait for each other. Point to point works for two or three systems and becomes unmaintainable beyond that. For most companies the right default is an integration layer (sometimes called a middle layer), which centralises the mapping. A partner portal exposes a controlled slice of your systems to distributors or customers, while 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. The current specification for documenting their HTTP APIs is OpenAPI 3.2.1, a patch release published in September 2026.
Key Takeaways
- Count your connected systems before you pick a pattern, because the count largely decides between point to point and an integration layer, whatever type of systems they are. 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.
- Treat a partner portal as access control first and user interface second. Scope every query to the partner making it and enforce that scope on the server. Every write also needs an audit record.
- OpenAPI 3.2.1, a patch release published on 10 September 2026, is the current specification, but many guides and generators still target 3.1. Check what your tooling emits before you standardise on it.
- Make writes idempotent first, since that is the single highest value design decision in any integration. Without idempotency, every network timeout risks a duplicate order and every retry becomes a gamble.
- Integration work is mostly data reconciliation, so plan the budget around it. Two systems will disagree about what a customer or a price is, and resolving that disagreement is where the project time goes.
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 a data breach with a nice layout, and filtering like that is the most common serious defect we find in existing portals.
Roles that match how partners work. Behind one distributor account 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 replaces manual work. The portal earns its cost by absorbing work someone currently does by email, such as order status, invoice history, stock levels and returns. If every meaningful action still ends in a phone call, the portal is only a viewer.
Search built for your catalogue. Partners search industrial and technical catalogues by specification and part code instead of marketing name. Generic text search over a catalogue like that is the reason they give up and call the sales desk.
An audit trail. Record who changed what, when, and on whose behalf. You will need it the first time a partner disputes an order, which will happen sooner or later.
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 what lets you operate an integration without having to babysit it.
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 and generate from it. A specification 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. The 3.2 feature set arrived with version 3.2.0 on 19 September 2025, so confirm your generators support it before you rely on them.
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. Use one error shape and meaningful status codes, and put 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, while one 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 and embedded in a partner system somebody else maintains, so nobody can rotate it and it outlives the project.
When Not to Build This
Plenty of integrations do not need 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 proprietary, when volume makes per operation pricing painful, when the data cannot leave your infrastructure, or when the integration is a product feature in its own right.
Our comparison of GraphQL and REST deals with choosing the API style itself. If an AI agent will consume the API, read MCP versus direct API integrations for 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 run from the first commit, and a senior engineer reviews 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. The purchase history middle layer we built for a multi outlet jeweller unified invoices, returns, and exchanges across every outlet.
The backend practice sits under Node.js development and full platform builds under custom software development. If you want API capacity inside your own team, you can hire Node.js developers.
I have spent years on the consuming side of APIs other people built, 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 versions and their publication dates, 19 September 2025 for 3.2.0 and 10 September 2026 for the 3.2.1 patch, come from the revision history in the official specification. The client outcomes are from our own case studies, linked above. The pattern guidance reflects how we build, and no published benchmark sits behind it. The connection growth point is 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 every system talks to instead, so each new system adds a single connection. 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.1, a patch release published on 10 September 2026 that keeps the 3.2 feature set introduced by 3.2.0 on 19 September 2025. Check that your documentation renderers, client generators, and validation middleware support 3.2, because a good deal of tooling still targets 3.1 and will silently ignore newer constructs.
Do I need an API gateway?
In most cases yes, 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, the application often handles those features better, and the extra component adds cost with no 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 them 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?
A focused integration between two well documented systems is a matter of weeks, while anything involving a legacy system with no specification takes as long as discovery takes. 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.
Conclusion
Integration quality comes down to where the mapping lives and whether writes are safe to retry. Five habits keep an integration from becoming the fragile part of the system, namely centralising the mapping, making every state changing request idempotent, versioning from the first release, documenting with OpenAPI 3.2 and generating from that document, and scoping every partner query on the server.
The API style decision is covered in GraphQL vs REST, and agent facing integration in MCP vs direct API integrations. To have this built or reviewed, start with Node.js development or contact us.
