API Development

03

An API is a product with its own users

Most software teams treat the API as plumbing for their own screens. That is a leak of ambition. An API has its own customers — engineers, partners, systems, your future self — and they each measure it differently: does it work? is it stable? is it documented? does it explain its failures? We engineer the API as the product it actually is.

• The contract is the product — the URLs, the fields, the status codes and the error shapes are a public agreement; once consumers rely on them, changing them breaks real systems.
• Design for the caller, not the database — the response shape is decided by what the consumer needs, not by the table behind it.
• Consistency is the first feature — naming, pagination, errors, dates, casing — one way of doing things everywhere, so a caller's pattern for one endpoint works for all.
• The API is versioned, always — every breaking change ships as a new version while the old one keeps working, because the cost of a quiet break is a partner's incident, not your deploy.
• The sandbox is real — developers can build against a true-to-life environment with test keys and fixtures before they point production at you.
• Documentation is part of the deliverable — interactive, browsable, with real examples, that reduces the distance between 'I found it' and 'I shipped it'.

The test of an API is uncomplicated: a stranger with the documentation should integrate on the first attempt, and a partner who integrated two versions ago should still work today. Everything else is detail.

04

The design: how a good contract is shaped

A well-designed API is a specific, teachable craft — the same discipline that makes a good spreadsheet or a good form. Each choice below is a promise to whoever calls you:

• Resources, not verbs — the API models things: invoices, tenants, bookings, payments, properties — and acts on them with clear, idempotent operations.
• Semantic status codes — 200 means done, 400 means your request was wrong, 401 not authenticated, 403 not allowed, 404 absent, 409 a conflict, 422 a shape error, 429 slow down, 5xx ours not yours.
• Consistent error contracts — every failure returns code, message, field, and a stable error type, so a client can act on the failure rather than parse it.
• Pagination that does not lie — stable cursors or page numbers, explicit ordering, total counts, so a list can be walked completely exactly once.
• Dates that travel well — ISO 8601 with timezone, everywhere, so a timestamp means the same moment in Nairobi and in the logs.
• Idempotency built for retries — a caller can repeat a payment, a send or a mutation with the same key and get the same result, never a double effect.
• Partial failure is honest — batch operations report which items succeeded and which failed, with their individual errors, instead of pretending one huge all-or-nothing.
• Backward-compatible evolution — add fields, never remove them; add optional params, never repurpose existing ones — so old clients keep working as the API grows.

Every design decision above is a small trust deposit with the people who build on you. An API that keeps its promises quietly is the API that becomes the backbone of someone else's product.

05

Versioning and the living contract

APIs that never change stagnate; APIs that change carelessly break partners. Versioning is how a live API improves without punishing the customers who believed in it:

• The version lives in the URL or header — a visible, explicit choice; the caller declares which contract they speak, and the API honours it.
• The old version is kept alive — sunset dates, deprecation warnings in headers, migration guidance — so partners can move at business speed, not your deploy speed.
• Breaking changes are announced, not discovered — deprecation notices, changelogs and a migration window by contract, so no consumer is ever ambushed by an API that quietly changed.
• Additive wins are the norm — most improvements add fields and endpoints without a bump; a new version is reserved for changes that genuinely break.
• The sandbox tracks the moving target — developers can test both current and next versions side-by-side, so their upgrade is a rehearsal, not a leap.
• The contract is machine-checked — schema validation and contract tests refuse a deploy that breaks a documented behaviour, so the promise is enforced, not remembered.

Versioning is the difference between an API people build their business on and an API people flee. We keep the platform's promises so the platform keeps its partners.

06

Security: the API as a public door

An exposed API learns within minutes how much of the internet is hammering for free — scanning paths, trying default keys, probing for mistakes. Security is not a layer; it is the standing posture of every request that arrives:

• Permissions before the code runs — the gateway and the entry authenticate and authorize before any business logic sees the payload.
• Scoped, revocable tokens — API keys and OAuth2 tokens carry exactly the scope their user needs — read, write, admin — and can be revoked instantly, per consumer.
• OAuth2 done properly — authorization-code flows with PKCE for real users, client-credentials for server-to-server, short-lived access tokens with refresh — not a token that never dies.
• Keys never in the response — tokens are issued, not echoable; secrets are never returned by an endpoint a human might screenshot.
• Input is refused until it is safe — shape validation, type checks, size limits and safe-by-default handling of every payload before anything is stored or executed.
• Rate limits enforced at the gateway — per-key, per-consumer-class and per-IP windows; the gateway refuses before the backend pays the cost.
• Abuse detection that notices — spikes, enumeration, unusual consumers and repeated failures are surfaced, because the quiet attack is the dangerous one.
• The OWASP list as tests — IDOR, injection, enumeration, mass assignment, CSRF and open redirects are executable checks that fail a deploy, not slides from a talk.

We harden our own payments API against the internet every day. An API on our watch is built as if its keys are already half-leaked and the internet is already curious — because both are true for every API eventually.

07

The API security checklist in practice

Below is the concrete checklist we run against every API we build or audit. Each item is a real control with a real test — the same ones that catch problems on live systems:

• Authentication — keys and OAuth2 with scopes; short-lived access tokens; refresh with rotation; MFA on admin surfaces.
• Authorization — every endpoint resolves who the caller is and what they may do — owner-scope checks server-side, never hidden buttons.
• Rate limits — per-key and per-IP windows at the gateway for every endpoint that costs work or touches money.
• Injection — parameterised queries everywhere; no string-built SQL; payloads shape-validated before use.
• Enumeration resistance — identical responses whether an email, phone or ID exists or not; registration and reset flows rate-limited.
• Secrets — no keys in code, bundles or documentation; managed secrets with rotation; never logged, never echoed.
• Tokens with least privilege — each consumer key scoped to exactly what its work requires, revocable individually.
• Verification of callbacks — signatures checked, payloads schema-validated, replay protected, idempotent by design.
• Audit logging — every authenticated action logged with actor, timestamp, outcome — append-only and protected.
• Dependency hygiene — frameworks and parsers scanned and current, because an API is only as honest as the code it imported.

This checklist saved real products on real nights. Every item corresponds to a class of exploit we have seen in the wild — including inside software that believed it was already secure — and each has a test that runs before deploy.

08

Auth and identity on the API

Identity is the first conversation a caller has with an API, and the wrong one poisons everything that follows. We build auth with the current best practice handling humans, machines and the awkward in-between:

• Bearer tokens with real lives — short access tokens, refresh cycles, and revocation that applies immediately, not 'next logout'.
• OAuth2 for delegated access — the classic: the user grants a third-party scope, the third party gets a narrow token, the user can revoke it.
• PKCE on public clients — the flow mobile and single-page apps use is injection-proof, because a leaked code challenge is useless without the verifier.
• Client credentials for machines — server-to-server principals with scopes and rotating secrets, so a CI pipeline or a partner system has its own honest identity.
• Password hashing the hard way — bcrypt or argon2 with per-user salts — never legacy hashes, never reversible, never the same salt twice.
• MFA where the surface matters — admin scopes, payment operations and partner consoles demand a second factor, because a stolen bearer token is a stolen account.
• Session and key management surfaces — users can see their tokens, revoke a single one and kill all sessions, because identity should be answerable to its owner.

We have run real OAuth, magic-link, device-link and session-light gates on a live platform. Modern identity looks unglamorous: short lives, verified grants, and the ability to say no instantly.

09

Webhooks you can trust — in both directions

Webhooks are where integrations either shine or silently corrupt data. A signed, idempotent, retried and dead-lettered webhook delivery is the difference between a partner that trusts you and a partnership that ended in blame at 3am:

• Signed payloads both ways — we sign every webhook we send and verify every webhook we receive, so receivers (and we) can prove who sent a message.
• Idempotent by design — every event carries an ID; redelivering the same event does not create a duplicate in whoever receives it.
• Ordered and durable delivery — events are delivered in order where order matters, and held durably until acknowledged, so a receiver restart loses nothing.
• Retries with backoff and a dead letter — a failing receiver is retried gently, then the event rests in a visible dead-letter queue with its payload, not in the void.
• Signature verification that means it — HMAC or asymmetric signatures over the raw body, checked against a constant-time comparison, so timing attacks find nothing.
• Replay protection — event timestamps and nonces mean a replayed delivery cannot be applied twice to the receiver's world.
• Delivery observability — a dashboard that shows delivered, pending, failing and dead-lettered events per receiver, so 'your webhook never arrived' is a question with a screenshot.

Our own payments platform lives on verified, idempotent callbacks — the exact discipline Daraja, C2B, B2B and B2C require for real money. A webhook we send is a promise we can prove; a webhook we receive is a claim we verify before we act.

The loop we run for real-money callbacks (this is the part that separates a toy from a platform):

• A callback is a claim, not a proof — the backend queries the gateway's own status/query API before crediting, so a forged or replayed callback cannot move money.
• Verified paid → credit — only a genuinely verified success settles; the transaction flips to confirmed and the ledger writes in the same atomic step.
• Transport or query error → retry signal — the correct response keeps money pending so the gateway re-sends, never half-crediting and never double-counting the retry.
• Definitive 'not paid' → acknowledge, never credit — the claim is accepted with an acknowledgement, the money stays untouched, and the mismatch is logged for reconciliation.
• Idempotency keys plus terminal-state guard — replaying the same event always returns the same settled answer; a refund can only ever reverse one matched send, once.
• Correlated both directions — outbound money carries a reference the gateway echoes back, so a callback can be matched to its send by that reference, never by guesswork.

10

Rate limiting, quotas and abuse control

Every good API needs a policy for 'how much is too much' — per key, per consumer and per spike. Limits are not punishment; they are how a shared resource stays healthy for everyone:

• Per-key and per-consumer-class limits — a free plan's token, a partner's token and an internal system's token each carry their own budget.
• Enforced at the gateway — the limit is refused before the backend pays the cost, so one runaway key cannot consume a shared database.
• Quotas that regenerate honestly — per-second, per-minute, per-day and per-month windows with clear headers telling the caller how much remains.
• 429 done properly — Retry-After is honoured, the caller is told why and when, and the client library translates it into a graceful wait, not a crash.
• Burst allowance with a refill — a leaky bucket permits short bursts without letting anyone stand on the pedal for hours.
• Abuse indicators surfaced — repeated 401s, enumeration patterns, spikes from one IP and unusual consumer behaviour go to an alert, not just a log.
• Human oversight — a console that shows which keys consume what, who is near a limit, and who to talk to before the lockout becomes a saga.

We enforce rate limits on every money path in our own platform — 5-second windows per user per action, checked at the gateway and inside logic. A well-limited API is a calm API; an API without limits discovers why it needed them in an incident.

On money APIs the rate limit is a financial control, so we make ours stronger than a generic throttle:

• Per-user, per-action windows, not just per-IP — shared NAT and family networks can't lock each other out, and a single account can't hammer a charge or withdrawal endpoint either.
• The limit window is also the evidence — rate-limit events are recorded in the same audit trail used for forensic review, so an abuse pattern is simultaneously an incident record.
• Errors carry the exact remedy — a blocked money action returns precisely what the caller needs (the amount to top up, or how long to wait), so the client acts instead of retrying blindly.
• Enforced inside business logic as well as at the gateway — a CDN bypass or direct-to-origin call cannot sidestep the limit.
• Limits apply per action, not per 'page' — deposits, withdrawals, sends and settlements each carry their own budget, because a burst of 1,000 tiny withdrawals is more dangerous than 1,000 reads.

11

Metering and usage analytics

You cannot run an API you cannot see being used. Metering is how the operators — and the billing team — know what the API actually does, who it serves and where the demand grows:

• Requests, errors and latency per endpoint — the daily truth of what is called, how often and how fast, in real time.
• Per-consumer usage — which keys consume what, so surprises (a partner that grows, a key that leaks) are visible immediately.
• Contract signals — payload sizes, pagination depth and error rate by version, so the oldest, heaviest clients to the migration conversation are known.
• The numbers behind billing — metered use mapped to plans and overage, so charging per call, per seat or per event is backed by real counters.
• Privacy-respecting telemetry — we measure the request, not the person: payload shapes and timing, never content we do not need to know.
• Dashboards that answer — today's throughput, today's errors, this week's trend — a screen someone opens because it is useful, not because it is required.

Metering and observability are the same muscle: you can only run, protect and bill what you can actually see. We instrument APIs the way we instrument money — every meaningful call measured, every limit visible.

12

Developer experience: the API people enjoy

An API's closest customer is a developer whose patience is finite. Developer experience is not a courtesy; it is the difference between partners who integrate in an afternoon and leads that hire someone else because your docs were exhausting:

• Interactive documentation — a console where a developer can try a request with their own key and see the real response before writing code.
• Real examples for real journeys — full request-and-response pairs for the five paths a new integrator actually walks, not a wall of field tables.
• Client libraries or documented clients — typed SDKs and reference clients that make the happy path fit in ten lines.
• Errors that teach — a 400 that says which field, what shape is expected and how to fix it beats a 400 that says 'bad request'.
• A sandbox that behaves — test keys, fixtures and deterministic test data, so a developer can build confidently without touching real records.
• Changelogs and migration guides — what changed, when, and exactly what a consumer must do to move — written for humans, not release notes.
• Quick starts that work — a first-request path that completes in minutes, because nothing kills an integration faster than a falsified quick start.

The highest compliment an API receives is not 'it's fast' — it is 'I shipped my first call without asking anyone'. We design the surface so that silence is the normal outcome.

13

Async and event-driven APIs

Not every API answers immediately. Long tasks, batched processing and event streams want a different shape — and the honest API says clearly which kind it is:

• Synchronous where instant is true — reads, validations, small mutations — answered in the request's lifetime, honestly.
• Async where work takes time — a 202 Accepted with a status resource or an event on completion, so the caller is not asked to hold a connection hostage.
• Status and result endpoints — 'started', 'processing', 'done', 'failed' — with the result retrievable when it is ready.
• Event streams as first-class — webhooks and queues deliver the outcomes to the interested parties, so nobody polls forever.
• Idempotent submissions — starting the same work twice with the same key yields one job, returned the same way every time.
• Honest failure visibility — a failed async job gives the consumer a reason and a retry path, not a silent forever-pending.

A confusing API hides its asynchrony; a confident API declares it. We design each operation to be either honestly synchronous or honestly event-driven — and never silently kind-of-both.

14

Performance and scaling the API

An API that is fast at a thousand calls and crawling at a million was built for the smaller number. The discipline below is what keeps an API's promises as the callers and the data grow — for real, not on a slide:

• Fast queries, not fast code — indexes, query plans and N+1 removal decided with the actual workload, because the database is almost always the real ceiling.
• Caching with correct invalidation — hot reads served from a cache whose eviction is right, so nothing stale is ever served near money, entitlements or freshness.
• Connection discipline — pooled connections, short transactions and timeouts, so a spike in callers cannot exhaust the database.
• Vertical then horizontal, honestly — a bigger machine where the work says so; more instances where the shape of the traffic says so.
• Timeouts and retries inherited by every dependency — a slow partner becomes 'we waited, we retried', never a frozen request.
• Load rehearsed, not assumed — the API exercised at the rates and payload sizes the business actually promises, so 'unlimited' has a number behind it.

We have profiled APIs where one missing index turned a partner's call into a thirty-second crawl, and one N+1 query quietly tripled database load. Performance is a design property, found before the users feel it — and measured again after.

15

Testing and deploying the API

An API's clients cannot be regression-tested by a browser; the contract must be proven by machine, on every change, so the people who depend on you are never surprised by a deploy:

• Contract tests — the documented behaviour of every endpoint is executable, so a change that breaks a promise fails the pipeline before it ships.
• Schema validation on input and output — every request and response is validated against its shape, so an accidental wrong field type cannot ship.
• Security tests as a discipline — the OWASP checklist as executable checks run before every deploy, not as a quarterly audit.
• Load and latency budgets — p95 budgets wired into CI, so a release that makes the API slower fails the build.
• Migration-safe deploys — backward-compatible changes and versioned additions shipped through a pipeline with a rehearsed rollback.
• Staging that mirrors production — the API's contract, keys and data shape rehearsed in a true staging environment before production sees a byte.

We deploy APIs the same way we deploy payments — in small, proven, reversible steps. A release that passes our API suite is a release we can ship before lunch and stand behind after dinner.

16

How we build and run APIs

The same engineering discipline shown throughout this list — visible, iterative and ending with the customer owning everything — is how an API gets built:

• 01 · The consumers first — who is calling, what journey they walk, and the five paths that must work before the hundred niceties — written before the first route.
• 02 · The contract — resources, status codes, errors, pagination and idempotency — the agreement drafted before the implementation.
• 03 · The security posture — auth, scopes, rate limits, verification and the OWASP controls as the foundation, not the finish.
• 04 · The core — the endpoints built against one trusted data layer, with contract tests that enforce the promises.
• 05 · The webhooks — signed, idempotent, retried and dead-lettered deliveries — the trust machinery for the integrations.
• 06 · The developer experience — interactive docs, examples, sandbox and quick starts — so a stranger ships on their first attempt.
• 07 · The observability — metering, logs, alerts and per-end-user dashboards from day one, because an API that cannot be seen cannot be run.
• 08 · The staging and the pilot — contract and load rehearsed against staging, then a controlled first wave of real consumers.
• 09 · The running and the handover — versions maintained, sunset dates kept, metering watched, and the code, docs and pipeline handed to the customer.

You own the code, the contract, the pipeline and every key. No lock-in, no hostageware, no 'it only works in our basement' — the API other people build their business on is an API you own and can run anywhere.

17

Honesty about APIs

Because an API becomes part of other people's software, we are direct about the realities you will meet on every build:

• Contract stability is a long-term promise — once third parties rely on your API, every change carries a real cost to them; versioning and deprecation are ongoing work, not a ceremony.
• Security is continuous, not a release — an API that ships secure is good; an API that stays secure is a discipline of updates, audits and abuse monitoring.
• Developer experience is earned — docs, sandboxes and client libraries are maintained, and the moment they rot, integrators feel it immediately.
• Webhooks are where trust breaks — payload signing, idempotency and dead-letter handling are the difference between a flaw and a feature, and they cost real engineering to get right.
• Performance is decided early — query design, caching and limits chosen at the start become the API's reputation; retrofitting speed is far pricier than designing it.
• You own the contract — the code, the documentation and the pipeline are yours, so the API your partners trust can never be held hostage by its builder.

Honest scoping is part of the contract too. We will tell you when an API is overkill, when a webhook is the wrong shape, and when your real need is a clean integration rather than a public surface.

The toolchain

The API toolchain

Every layer below is chosen to make an API trustworthy: a contract that keeps its promises, security that treats every request as hostile, rate and abuse control that keeps the resource fair, webhooks that can be proven, and observability that shows the whole picture. These are the exact patterns behind our live payments API — verified, idempotent and hardened.

Lifecycle

The API lifecycle — from first route to a platform other businesses rely on

An API is not a delivery; it is a living contract with its own users, evolving by version, protected against the internet and proven by test. This is the lifecycle we carry every API through.

Closing

More than development

API Development is where software meets software: a contract people build on, protected against the internet, proven by test and measured with honesty. That includes:

An API is the only part of your product that other people's software depends on — and the only part that cannot hide behind a good interface. When the contract is stable, the security is real, the webhooks can be proven and the errors teach, an API becomes the quiet backbone that other builds rest on without ever noticing it is there.

We build APIs the way we build money systems — because at the centre of Kenyan software there is almost always an API moving money, identity or records. Every endpoint, every token, every webhook and every rewritten retry is held to the standard of real trust.