Limited availability. Q4 slots filling now ·
Back to Articles

API Integration Guide: Connect Your Systems and Scale

An API integration guide written by a senior engineer who has shipped them at a $1B+ unicorn. REST vs GraphQL vs webhooks, five integration scenarios, security, real costs, and the bolttech case.

By Adriano Junior

The hidden cost of disconnected systems

API integration is the work most teams keep postponing because it feels invisible. Then a customer asks for a refund and four people spend two hours hunting down the charge across three tools. According to McKinsey research on the economic potential of generative AI and automation, repetitive back-office work consumes a meaningful share of working hours across industries — and most of that work is people moving data between systems that should be talking to each other.

I have spent 17 years building software, with 250 plus projects shipped. The single largest piece of that body of work was at bolttech, the $1B+ unicorn fintech, where I led the Payment Service that orchestrated 40+ payment providers behind one API. So I have a slight bias here. I think most companies underspend on integration and overspend on cleanup work that integration would have prevented.

This guide covers what APIs are in business terms, the three types worth knowing, five integration scenarios that pay for themselves, security I would not skip, real cost ranges, and the bolttech case study you can read end to end.

TL;DR

APIs are the plumbing connecting your software so data flows automatically instead of through copy-paste. Three types: REST (the default), GraphQL (flexible queries for complex data), webhooks (real-time push). Five scenarios that pay back fast: payment processor, CRM-product sync, shipping, analytics pipeline, and SSO. Security floor: OAuth or signed API keys, rate limits, TLS, encrypted secrets, signed webhooks, and audit logs. Cost ranges run from $3K for a focused payment integration to $20K plus for an analytics pipeline, with maintenance at 10 to 20 percent of build cost per year. The bolttech case at the end is mine — 40+ payment providers, 99.9 percent uptime, zero post-launch critical bugs.

Table of contents

  1. What APIs are, in business terms
  2. API types: REST, GraphQL, webhooks
  3. Five common integration scenarios
  4. API security I would not skip
  5. Integration costs and timeline
  6. Case study: bolttech payment integration
  7. FAQ
  8. Reflecting on what actually moves the needle

What APIs are, in business terms

API is short for application programming interface. The plain version: it is a contract between two pieces of software that says "I have this data or this capability. Here is how to ask for it, and here is what you will get back."

A simple analogy. A restaurant menu is an API specification. You are the client. The waiter is the request. The kitchen is the server. The plate of food is the response. If the menu changes and you do not know, your order breaks. Same with APIs.

In software, the same exchange looks like this:

Client (your app): "Hey Stripe, refund this charge ($50)."
Stripe API:        "Done. Proof: refund_id=rf_1234567890"

Why this matters for the business

Without APIs you have data silos. Customer info in one tool. Payments in another. Product usage in a third. Support tickets in a fourth. Shipping in a fifth. Getting a single view of one customer means a person opening five tabs. That person is the bottleneck and they are also the hidden line item on your P&L.

With APIs the systems talk to each other. A signup in your product creates a record in the CRM. A purchase updates accounting and triggers a receipt. A shipment status pushes back to the customer dashboard. Nobody has to remember to do anything.

I worked on the Imohub portal where indexing 120,000 plus property listings without API automation would have been a non-starter. The whole site existed because the integrations existed. Read the Imohub real estate portal case study for the full architecture.

API types: REST, GraphQL, webhooks

REST: the industry default

REST runs on plain HTTP verbs (GET, POST, PUT, DELETE) hitting endpoints. The server returns JSON.

GET /api/customers/123
→ { "id": 123, "name": "Acme Corp", "email": "..." }

POST /api/orders
→ { "order_id": "ord_456", "status": "pending" }

Why I default to REST for most projects: every language has a client, every junior engineer can read it, and every API monitoring tool knows what to do with it. Stripe, Twilio, GitHub, AWS — all REST.

Where it gets ugly: over-fetching (you wanted a name and email; you got 47 fields), and N+1 patterns where you call one endpoint to get a list of IDs and then 50 endpoints to get the details. There are workarounds, but at some point you start wishing for GraphQL.

GraphQL: ask for exactly what you need

GraphQL lets the client describe the shape of the response. Server returns that and only that.

query {
  customer(id: 123) {
    name
    email
    orders {
      id
      amount
      status
    }
  }
}

You get the customer name, email, and their orders in a single round trip. Nothing extra. Strongly typed. Real-time subscriptions are part of the spec. The official GraphQL specification is worth a slow read if you are deciding between approaches.

Cost: more setup. Caching is harder than REST. Tooling is thinner. I would only reach for GraphQL when I have many data relationships and many client types asking for different shapes of the same data. Shopify and GitHub both ship GraphQL APIs because their data graph is genuinely large.

Webhooks: the server tells you

Polling an API every minute to see if anything changed is wasteful. Webhooks invert the model. The server sends you an HTTP POST when something happens.

Stripe webhook → POST https://yoursite.com/webhooks/stripe
Body: { "event": "charge.succeeded", "amount": 4999, ... }

Real-time. Cheap. The catch: you need a public endpoint, you need to verify the signature so nobody forges it, and you need to handle the same event arriving twice (idempotency). Skip those steps and webhooks become a security incident waiting to happen.

Use webhooks for anything you would otherwise poll for: payment confirmations, shipping updates, deal stage changes, build statuses. If you find yourself running a cron job every minute, you probably want a webhook instead.

Five common integration scenarios

1. Payment processor integration

The before picture: payments live in the processor. Accounting lives somewhere else. Someone reconciles by hand on Mondays. Refunds take two days to flow through.

The after picture:

  1. Customer checks out. Processor approves the charge.
  2. Webhook fires. Your backend receives it within seconds.
  3. Backend updates the database, posts to accounting, fires the receipt email, and decrements inventory.
  4. Reconciliation is real-time, not weekly.

What it actually saves: roughly 5 hours a week of manual reconciliation, plus all the customer trust you lose when refunds are slow. At a 5-hour-per-week baseline and a $150/hour fully loaded labor cost, you are looking at about $39K a year. A typical Stripe integration is $3K to $8K. Payback in 10 to 12 weeks is normal.

The only non-negotiable on this one: verify webhook signatures. Stripe signs every webhook. If you skip that step, anyone who learns your endpoint URL can forge events. Yes, that has happened. No, you do not want it to happen to you. If Stripe is the integration you need to ship next, the Stripe integration services page covers what is included in a typical engagement and how long it takes.

2. CRM and product data sync

The before picture: the CRM has contact info and deal history. The product has usage events. Sales is flying blind into renewals. Support has no idea who is paying you a lot of money and who is paying you nothing.

The after picture:

  1. Signup creates a contact in the CRM.
  2. Feature usage logs an activity on the contact timeline.
  3. CRM webhooks fire when a deal stage changes (closed-won, churn risk).
  4. Sales calls the right people at the right time. Support routes by account value.

A two-way sync between Product and CRM is one of the highest ROI integrations I have built. Reps stop doing data entry. Support stops asking "is this person on a paid plan?" Churn signals show up before the customer churns. Typical build is $5K to $15K depending on how many objects you sync.

3. Shipping system integration

If you are typing addresses from your e-commerce admin into FedEx by hand, you have already paid for this integration in lost weekends.

The flow:

1. POST /shipments  (address, weight, items → tracking number)
2. GET  /shipments/{id}  (status check)
3. Webhook: shipment.delivered

Build cost: $4K to $10K. Per-label fees are unchanged. What you get back is your operations person's afternoon. And the customer gets a tracking number the same minute they place the order, instead of "your order has shipped" three days later.

4. Analytics pipeline

Your product, website, payment processor, CRM, and support tool all generate events. If those events live in five different places, you cannot answer the question "which marketing channel produced the highest-LTV customers?" You can guess. Guessing is expensive.

The shape of the integration:

Product   → Event API ↘
Website   → Event API ↘
CRM       → Event API → Warehouse → Dashboards
Payment   → Event API ↗
Support   → Event API ↗

Tools like Segment, Snowflake, BigQuery, or a custom event collector all work. The hard part is not the pipes — it is agreeing on event names and properties. Spend the upfront day on a tracking plan or you will rebuild this integration twice.

Build cost: $8K to $20K. Ongoing: $500 to $5K a month depending on data volume.

5. Authentication and SSO

Ten internal tools. Ten passwords. An employee leaves and IT has to remember to revoke access in ten places. Security and compliance hate this. Auditors hate it more.

SSO with an identity provider (Okta, Azure AD, Auth0) collapses login into one place. OAuth 2.0 for user-facing flows. SAML for enterprise. OpenID Connect for modern setups. The NIST Digital Identity Guidelines (SP 800-63) are the canonical reference if you need to defend a design decision.

Cost: $3K to $10K to wire up the first time, plus identity provider licensing per seat. Worth it the moment your headcount crosses about 10 and certainly before any compliance audit.

API security I would not skip

Integration means opening doors. The defaults are not safe enough.

Authentication

API keys are simple but easy to leak. Rotate them every 90 days. Never log them. Never commit them. OAuth 2.0 is the standard for user-facing flows because tokens are scoped and revocable. Mutual TLS shows up in regulated finance and health where both sides need to prove they are who they say they are.

Default rule: OAuth for users, scoped API keys for service-to-service, with rotation.

Rate limiting

A bug in a client loop calls your API 1,000 times a second. Without rate limits, your infra goes down and your AWS bill goes up. With rate limits, the buggy client gets 429s and your team gets a Slack alert.

Implement rate limits on every API you publish. Respect rate limits on every API you consume. The OWASP API Security Top 10 lists rate-limit failure as one of the most common production incidents.

Encryption

In transit: TLS everywhere. No plain HTTP, ever, not even on the staging environment. At rest: API keys, tokens, and customer secrets encrypted in the database. AWS KMS or equivalent. Never roll your own.

Webhook signatures

Every webhook provider gives you a way to verify the message came from them. Use it. The check is small:

import hmac, hashlib

expected = hmac.new(
    webhook_secret.encode(),
    request.body,
    hashlib.sha256,
).hexdigest()

if not hmac.compare_digest(signature, expected):
    return "Unauthorized", 401

Skip this and webhooks become a forged-request vector.

Audit logging

Log who called what, when, and what came back. Not the data itself, just the access pattern. When something goes wrong, the audit log is what tells you whether your customer's data was actually exposed. Without it, you are guessing in the worst possible meeting.

Integration costs and timeline

Integration type Complexity Build cost Timeline Maintenance
Payment processor Low $3K–$8K 2–4 weeks $100–$300/mo
CRM sync Medium $5K–$15K 4–8 weeks $500–$1K/mo
Shipping Low–Medium $4K–$10K 2–4 weeks $200–$500/mo
Analytics pipeline High $8K–$20K 6–12 weeks $1K–$3K/mo
SSO/Auth Medium $3K–$10K 2–6 weeks $500/mo (license)

Where the variance comes from: API documentation quality (good docs cut weeks), provider responsiveness (slow vendor support adds weeks), and the team's familiarity with the protocol. A REST integration done by a REST-fluent team is fast. A GraphQL integration done by a team learning GraphQL is not.

A simple ROI worked example: 5 hours a week of payment reconciliation at $150/hour = $750/week. Annualized that is $39K. A $6K integration pays back in roughly 8 weeks and keeps paying after that.

For the long version of how I price work like this, see the custom web applications service page and the fractional CTO service page.

Case study: bolttech payment integration

bolttech is a $1B+ unicorn fintech backed by Tokio Marine and MetLife Next Gen Ventures. As a Senior Software Engineer there from January 2020 to April 2021, I led the Payment Service: one orchestration layer in front of 40+ payment providers across Asia and Europe.

Before

Each region had its own payment integration codepath. Adding a new market took weeks because every provider was a small rebuild rather than a configuration change. Reconciliation ran across inconsistent data shapes. Error handling was per-handler, not platform-level. Webhook signature checks were inconsistent. The system worked, but it did not scale.

After

A single Payment Service absorbed provider differences behind a clean API contract. Queues handled retries and idempotency. Webhook signatures were verified centrally. Reconciliation ran against a normalized event stream rather than provider-specific shapes. Adding a new provider became a config change with tests.

Headline outcomes

  • 40+ payment providers integrated under one orchestration layer
  • 99.9 percent platform uptime
  • 15+ new international markets launched
  • Zero post-launch critical bugs

Full write-up: bolttech: 40+ payment integrations.

What carries over to almost any payment integration

Three patterns from that work that I now reach for by default:

  1. Async queues beat synchronous handlers once you are past about 10 providers. The synchronous version stops being maintainable.
  2. Webhook signature verification and idempotency keys are not optional. Treat them as part of the protocol.
  3. A normalized event stream is what makes reconciliation possible at scale. Provider-specific shapes do not compose.

I applied a related normalization pattern at Cuez to drop API response time from 3 seconds to 300 milliseconds (a 10x improvement) and cut infrastructure costs by about 40 percent. Same idea, different domain. Read Cuez: API optimization from 3s to 300ms.

FAQ

Do I need APIs if I am a small company?

Yes, and probably more than a large one. The cost of manual data entry is heavier when you have fewer people. Even a single Stripe and Slack integration eliminates hours of busywork that scales linearly with growth.

REST or GraphQL?

Start with REST. It is simpler, the tooling is mature, and 90 percent of integrations are fine with it. Move to GraphQL when you have many data relationships, want to cut payload size for mobile clients, or have many client teams asking for different views of the same data.

How long does an integration take to build?

Simple ones (payment, shipping) land in 2 to 4 weeks. Complex ones (analytics pipelines, deep CRM syncs) take 6 to 12 weeks. Documentation quality and vendor support drive most of the variance.

What if the third-party API changes?

Most providers maintain legacy versions for 12 months or more. Build with versioning in mind from day one (/v1/, /v2/). Subscribe to deprecation notices. Budget 10 to 20 percent of the original build cost per year for maintenance.

Can I integrate without a dedicated engineer?

For simple cases — Stripe checkout via Stripe-hosted pages, Zapier between two SaaS tools — yes. For anything custom or anything carrying real money or PII, hire someone who has done it before.

How do I handle API downtime?

Degrade gracefully. Queue the request locally and retry. Log the failure. Alert the team. Have a manual fallback. The worst designs treat third-party APIs as if they will never fail. They will.

Should I build my own API?

If external customers or partners will consume it, yes. If it is purely internal, no — invest in integrating the SaaS APIs you already pay for.

A short tour of the protocols you will actually meet

REST, GraphQL, and webhooks cover most of what teams build, but in practice you will run into a few more during integration work. A short tour, in the order I usually meet them.

OAuth 2.0 and OpenID Connect. Standard for delegated access (let one app talk to another on behalf of a user). Almost every modern API supports it. The OAuth 2.0 RFC 6749 is the canonical spec. Read it once, refer to it forever.

SAML. Older enterprise SSO protocol. Heavier than OIDC, still required by many large customers' security teams. If you sell B2B above a certain customer size, you will end up implementing SAML.

WebSockets. Bidirectional, persistent connections for real-time work — chat, live dashboards, collaborative editing. Heavier than SSE but full-duplex.

Server-sent events (SSE). One-way push from server to client over plain HTTP. Often the right tool when you only need updates one direction (notifications, activity feeds). Cheaper than WebSockets to operate.

gRPC. Binary protocol on HTTP/2. Faster and stricter than REST. Strong fit for service-to-service backend traffic where both sides are yours and you can ship typed contracts.

Message queues (Kafka, RabbitMQ, SQS). Not strictly an API but they are how production integrations move at scale. The bolttech Payment Service ran on queues for retries and idempotency. Once you cross a few high-volume providers, queues stop being optional.

The right protocol is almost always the simplest one that solves your problem. REST plus webhooks covers 80 percent of integrations. Reach for the heavier tools only when REST clearly cannot do the job.

Versioning, deprecations, and the "API will change" problem

Third-party APIs change. Your own API will change. The integrations you build today are running against a moving target whether you plan for it or not.

A few rules I would not skip:

Version every API from day one. /v1/ in the path. Cheap insurance. The day you need to ship a breaking change, you will be glad it is there.

Subscribe to the provider's deprecation announcements. Stripe, Twilio, AWS, GitHub — all of them publish deprecation notices. Add the engineering team to those mailing lists and triage the notices monthly.

Pin to a specific version, not "latest." Let the upgrade be a deliberate decision, not an accident on a Tuesday morning when an SDK auto-updates.

Budget about 10 to 20 percent of the original build cost per year for maintenance. Some of that pays for upgrades. Some of it pays for handling provider outages. Most of it pays for the small refactors that prevent the next big rewrite.

Test contract changes in staging. When a provider releases a new version, run the integration test suite against the new version in staging before flipping production. The test suite is the spec, written down.

I have seen teams skip every one of these and survive. I have also seen teams skip them and lose a Saturday to a payment provider that quietly retired an endpoint. The cheap version of the work pays for itself the first time it saves you.

Reflecting on what actually moves the needle

The integrations that pay for themselves the fastest are not the most technically interesting. Payment reconciliation. Shipping automation. CRM sync. They are unglamorous and they save real money every month.

The integrations that look exciting on a roadmap — the analytics pipeline, the AI agent that writes summaries, the real-time collaborative whatever — usually pay back too, but later, and only if the data plumbing underneath was already clean.

I have one mild preference: if you are debating whether to ship the boring integration first or the exciting one, ship the boring one first. The exciting one will be easier when the data already flows. And boring integrations have a quiet upside, which is that nobody writes a postmortem about them at 2 a.m.

If you want a hand prioritizing your integration roadmap, get a quote in 60s. I have built integrations across payment processors (Stripe, Braintree, Adyen, and the 40+ at bolttech), CRMs (Salesforce, HubSpot), shipping providers, and analytics platforms.

Services I offer

Case studies

Related guides

Related Articles

All posts