Backend engineering / API
API development.
Contracts, permissions and integrations.
Plan REST resources, GraphQL views, realtime updates and provider integrations around actual consumers, data ownership and operating constraints. Define the contract, test forbidden actions and preserve released clients through implementation and handover.
Discuss API requirements βContents Β· API
Begin with consumers, records and permitted actions.
API development covers resource and endpoint design, authentication, object and tenant permissions, validation, documentation, provider integration and release evidence. An API is a contract used by web, mobile, internal and partner clients. Agree what each client may read or change before selecting a protocol, gateway or framework.
Plan Gateway β Service β Data separation with the OpenAPI contracts, tests, caching, connection pools and background work the application needs. Inspect the existing build before planning reuse. Existing-code repair, a new API and adapting a product base have different risks and acceptance needs.
Compare the current application and receiving team with the proposed design. A new gateway or version prefix does not automatically remove coupling, make every client compatible or establish production readiness. No project total, fixed delivery interval, staffing claim or commercial offer is adopted from the source.
Handover includes contracts, data and operating responsibility.
Specify source and history, dependency locks, resource and error contracts, OpenAPI documents, Postman collections or equivalent client examples, migrations, tests, infrastructure code, release artefacts, configuration templates and runbooks. Ask the receiving team to demonstrate a clean install, permitted operation, deployment and restored backup.
Separate custom IP assignment from framework, reusable platform, third-party package, template, asset and provider rights. Put branding, confidentiality, permitted reuse, support, exit help and account ownership in writing. Do not place production keys in the repository, logs, examples or shared handover material. Source delivery alone does not establish unrestricted ownership or independent operation.
Compare interaction models rather than universal speed ranks.
- REST: a resource-oriented architectural style commonly implemented over HTTP. Define URLs, methods, status codes, representations, caching and consumer contracts. Not every JSON endpoint satisfies every REST constraint.
- GraphQL: a typed query language and execution model for client-selected data. Resolvers, authorization, pagination, source calls, caching and demand controls still need implementation; field selection is not zero backend overfetch.
- WebSocket: a persistent bidirectional transport for selected live interactions. Define application messages, authentication, ordering, replay, reconnect and stale-state recovery. Socket. IO is not interchangeable with a bare WebSocket protocol.
- gRPC: generated contracts and RPC mechanisms can fit service communication. Inspect browser/proxy support, streaming, deadlines, errors and deployment rather than assuming it is impossible outside internal services.
A mixed system might expose REST to partners, a graph to selected clients, WebSocket updates and internal RPC. This is an option, not a required topology. HTTP/CDN caching depends on response semantics, identity, headers and invalidation; GraphQL caching does not universally require persisted queries. No protocol is always fastest, easiest or cheapest.
Seven decisions before an API engagement.
What should be built?
Inventory resources, consumers, operations, fields, errors, documentation and acceptance. Identify existing behaviour that must remain compatible.
How should versions and lists work?
Choose compatibility rules, deprecation, ordering, filters, cursor or offset semantics and client migration evidence. A version prefix alone is not a policy.
Which identity model?
Choose API keys, OAuth flows, sessions or another mechanism from caller and trust needs, then enforce object, tenant and field permissions. JWT describes a token format, not the entire permission system.
Which protocol?
Compare resource HTTP, graph selection, RPC and live messages on the actual consumers, data and operations.
How do providers connect?
Specify adapter contracts, credentials, errors, timeouts, retries, idempotency, callbacks and reconciliation.
What determines scope and cost?
Count resources, consumers, policy complexity, integrations, live features, migration and operating responsibility, then obtain current itemised terms.
Developer or team?
Name owners for contract, implementation, review, QA, release, documentation and incidents. Inspect evidence rather than treating a hiring model as a quality guarantee.
Gateway, service and data paths need explicit trust.
The source proposes a gateway for edge routing and selected cross-cutting controls; services for handlers, validation and business rules; and repositories or data access for persistence. Keep resource and consumer contracts explicit across those boundaries. A new route can still affect shared libraries, schemas, authentication and deployment.
Kong can be selected for routing, consumer credentials and rate limiting. Envoy or a configured mesh can support internal routing, TLS and traffic policy. These components are not universally installed together and their presence does not prove that direct service paths, forged forwarded headers or alternate routes are protected.
Centralize suitable shared controls without removing business authorization from the service that understands an order, account or workflow. Authenticate trusted caller context, reject spoofed identity and test every relevant ingress path. No automatic isolation, no-impact module addition or mandatory gateway standard is asserted.
The orders sample leaves the auth and query implementations out.
The FastAPI example defines Order(id, status, total_cents), an OrderPage with next_cursor, a /v1 router and GET /orders. A dependency named require_scope requests orders:read; fetch_orders receives the account, after cursor and one extra row. The handler trims the page and returns the last retained ID when another page exists.
- The imported app.auth and app.db helpers are absent. Comments asserting JWT verification or a keyset predicate are not implementation evidence. Inspect signature and claim validation, scope enforcement, tenant filtering, selected output and the actual SQL.
- The limit parameter is bounded from 1 to 200 with a default of 50. That bounds this declared parameter, not total API work, nested data, count queries, request sizes or every route. after has an integer type but no shown domain or account/filter binding.
- Correct keyset behaviour needs the same account, filters and deterministic unique ordering in the predicate and ORDER BY, with suitable indexes. ID order is appropriate only when its semantics fit the list. Mutable sort fields, backfills and deletions need a stated consistency model.
- The more/trim/last-ID pattern assumes the helper respects its requested ordered limit and returns rows with an id attribute. A broken helper is not repaired by this handler. Test empty, boundary, duplicate, unauthorized and concurrently changing data.
- OrderPage response validation and filtering can enforce a declared shape. They do not supply business authorization, valid status transitions or a currency contract. total_cents omits currency and domain constraints.
- A plain Depends call and a scope-like string do not themselves prove OAuth security-scope metadata in OpenAPI. Inspect the dependency security declarations and test actual rejected requests, not only the interactive docs.
The displayed code remains illustrative, not an installed order backend. Its introductory comments are qualified to avoid repeating missing-auth and automatic-documentation claims as verified facts.
Technical example
Source sample, not an installed backend or verified deployment. The limitations above apply.
# orders_api.py - illustrative versioned resource; auth helpers are not shown
# and cursor pagination; verify actual deployed OpenAPI path and settings
from fastapi import APIRouter, Depends, FastAPI, Query
from pydantic import BaseModel
from app.auth import require_scope # source assertion only; implementation omitted
from app.db import fetch_orders # keyset query: WHERE id > :after
class Order(BaseModel):
id: int
status: str
total_cents: int
class OrderPage(BaseModel):
data: list[Order]
next_cursor: int | None
v1 = APIRouter(prefix="/v1", tags=["orders"])
@v1.get("/orders", response_model=OrderPage)
async def list_orders(
after: int | None = None,
limit: int = Query(50, ge=1, le=200),
user=Depends(require_scope("orders:read")),
):
rows = await fetch_orders(user.account_id, after=after, limit=limit + 1)
more = len(rows) > limit # fetched one extra row to know if a next page exists
rows = rows[:limit]
return OrderPage(data=rows, next_cursor=rows[-1].id if more else None)
app = FastAPI(title="Orders API")
app.include_router(v1)Design resources, errors and actual compatibility tests.
Agree resource names, methods, identifiers, request and response schemas, status codes, error categories, pagination and filtering. Define business validation separately from syntax and data types. A valid JSON object can still be an illegal order transition or reveal a private field.
Use OpenAPI and client examples to describe the selected HTTP contract, security requirements and errors. Generated documentation can reduce drift but cannot prove runtime enforcement, semantic correctness or complete coverage of custom middleware, proxies and provider failures. Verify the served schema and released clients together.
Test successful and rejected operations, omitted and unknown fields, enum expansion, nullability, dates, money, concurrency, rate limits and downstream errors. Record whether clients reject unfamiliar fields or values. Documentation and a Postman collection are useful handover artefacts, not a replacement for contract tests.
Additive changes are not universally non-breaking.
A /v1 path is one versioning choice, not an HTTP requirement. Define compatibility across payloads, required inputs, defaults, enums, status codes, ordering, errors, permissions and meaning. Adding a field or enum value can break strict clients; keeping the same URL does not make a semantic change safe.
Use tested consumer contracts and actual usage evidence before introducing or retiring behaviour. The Deprecation response field is standardized by RFC 9745; Sunset by RFC 8594 indicates expected unavailability. They carry different information and do not migrate clients themselves. Publish migration guidance and a support policy appropriate to the consumers.
Keep old clients operating for the agreed coexistence period, verify traffic and owners, then remove only under the chosen policy. No inherited v1/v2/v3 diagram or guaranteed retirement interval is adopted. An offline mobile client or external partner may not upgrade on the same schedule as the server.
Define list consistency before choosing a cursor.
Keyset pagination can avoid increasing offset work when a query uses an appropriate indexed ordering and continuation predicate. It does not guarantee that no row is skipped or repeated under every insertion, update, deletion or backfill. Define whether the list is a moving view or a stable snapshot and test that promise.
Bind continuation to the relevant account, filters and sort as needed. Validate cursor type, length, integrity or opacity requirements and expiry where chosen. Use a unique tie-breaker for non-unique sort fields; prevent a user changing a cursor from changing access policy. A signed cursor is not authorization either.
Offset pagination may fit page-jump interfaces, but it needs predictable ordering and query/cost evidence. Bound page sizes and expensive filters, whitelist sort keys, profile query plans and count metadata, and test tenant predicates on both rows and totals. Caching and connection pooling cannot make every large-list query flat in latency.
Authentication is separate from object and workflow permission.
API keys can identify a consumer or project and support rotation and quotas. Decide scopes, storage, expiration and leak response; do not put privileged server keys in a public client. A key identifying a customer does not establish permission to read every order or perform every action.
OAuth supports multiple flows, including machine-to-machine client credentials as well as delegated user access. For applicable public-client authorization-code flows, current OAuth security guidance requires PKCE. Choose issuer, redirect rules, audience, scope and token handling for the actual application rather than copying a tutorial grant.
JWT is a token format, not an alternative category to OAuth. Validate approved algorithms, signature, issuer, audience, lifetime and required claims for the selected token profile. Key rotation, logout, revocation and current user state can require shared state or other checks; a JWT does not universally remove database access.
Enforce record, tenant, field and workflow-state rules wherever data or effects are reached. Test changing IDs, alternate routes, mass assignment, batch operations and role changes. HTTPS, input/output controls, CORS and gateway validation have distinct jobs. Neither CORS nor a successful login is object authorization.
Quotas need an actual state and failure model.
Define identities, keys, routes, burst and sustained limits, concurrency, body size, expensive work and downstream provider budgets. Return documented errors and retry information where appropriate. A single per-minute numeral in an illustration is not a verified customer allowance or capacity claim.
Kong rate-limiting behaviour depends on plugin, version, configuration, policy and state backend. Inspect multi-node consistency, outages, bypass paths and trusted forwarded identity. Local state on several nodes is not automatically one global quota. Paid features and hosting are separate choices, not included merely by naming the product.
Keep timeouts, bounded retries and circuit-breaker policies aligned across client, gateway, service, database and provider. Multiple retry layers can amplify load and repeat effects. Rate limiting does not cure an unbounded database query or prove a service is safe from abuse.
Adapters preserve boundaries, not automatic interchangeability.
Payments, KYC, maps, SMS, shipping and accounting providers have different credentials, contracts, states, quotas and failure semantics. Keep adapters and typed internal outcomes, but do not promise that changing a payment provider affects only one module. Settlement, refunds, onboarding and reconciliation may change as well.
Test sandbox paths and provider-specific production differences, accounts, approvals, network rules and limits. A sandbox success is not proof of production approval, live funds movement or regional support. Store and rotate real credentials through a secure operational process, not the source tree.
Set deadlines, safe retry conditions, backoff and budgets. Classify rejected, uncertain, accepted and completed operations; use reconciliation when a timeout leaves the outcome unknown. A local database transaction cannot make a remote payment atomic.
Retries require provider-specific effect protection.
Define idempotency-key scope, request comparison, persistence, expiry and concurrent handling for the operation. Keep a stable key for a retry of the same intended effect. A new key or an expired record can create a new operation; merely sending a header does not guarantee duplicate prevention.
Stripe documents distinct API v1 and v2 retry behaviour. Its v1 layer records the first executed result, including some failures, and checks parameter reuse; that is not a universal rule for every provider or API version. Inspect the selected account, endpoint and current contract rather than generalizing a slogan about never charging twice.
For incoming callbacks, validate the provider signature with its required raw body and endpoint secret, timestamp/replay rules and actual event context. Deduplicate deliveries and handle out-of-order events. A signature authenticates a delivery under its scheme; it does not replace application permissions or prove a business state transition is still valid.
Persist or durably enqueue accepted work before an appropriate acknowledgement, with failure recovery, retry and dead-letter inspection. Queueing a slow handler can help response time but cannot guarantee the provider never retries. Separate receipt, processing and reconciled business completion.
Measure data work, caches and worker capacity.
Profile representative resource queries and provider calls, selected fields, indexes, batching and connection-pool limits. Batching can reduce particular N+1 patterns; it does not prove all data access is efficient. Pools have queueing and database capacity limits, while excessive parallel work can exhaust downstream services.
Use Redis or another cache only with explicit keys, identity/tenant scope, freshness, invalidation and failure rules. Public/CDN caching of private responses needs careful headers and access boundaries. A cache hit rate is not a guarantee of flat latency as traffic grows.
BullMQ, Kafka consumers or another worker mechanism can move heavy reports and integrations off request paths. Specify durable acceptance, duplicate-safe effects, retries, poison work and status visibility. A quick accepted response does not mean the report, message or payment has completed.
Load-test release artefacts against representative infrastructure and data, with stated workload, percentile latency, error, saturation and recovery evidence. Do not turn a developer benchmark or an illustrative calls-per-hour figure into a production capacity promise.
External developers need a lifecycle, not only endpoints.
For partner or public APIs, define consumer onboarding, credential issue and rotation, scopes, quotas, interactive documentation, examples, SDK or collection maintenance, changelog and support routes. Protect administrative key-management actions with actual permissions and audit.
Document sandbox limitations, sample data, event schemas, webhook retry behaviour, pagination, errors and version transitions. SDKs need their own version, runtime and release tests. A public schema, generated client or gateway dashboard does not prove a developer can safely complete the business workflow.
Preserve released contracts during a takeover. Audit code, specifications, secrets, consumers and incidents before moving infrastructure or replacing authentication. Agree what compatibility means and what needs a coordinated migration.
Release the contract, data and policies together.
Record runtime versions, dependency locks, gateway configuration, routes, schemas, data migrations, workers, credentials and network trust. Test actual health, permitted and forbidden smoke operations and released-client compatibility after deployment, not only process startup.
Monitor request rate, errors, duration, saturation, provider failures, queue lag and uncertain effects with private-data-aware logs and traces. Avoid exposing tokens, identity documents or sensitive request bodies. Name alert and incident owners and define retention and access.
Coordinate rollout and rollback or forward-fix across API versions, data changes and clients. Restoring a binary does not undo sent messages or settled payments. Backup restoration and reconciliation need exercised procedures; multi-region hosting does not automatically solve data residency, consistency or downstream outages.
Three engagement models remain distinct.
Adapt a product base
Inspect the actual backend, clients and administration features, licensing and reusable modules. Agree configuration, branding, custom endpoints, migration and acceptance separately. Catalogue counts do not prove suitability.
Build a custom API
Define resources, consumers, identity, permissions, integrations, documentation, tests, release and receiver needs. State what is excluded and which providers or accounts remain external dependencies.
Continue an existing API
Agree change review, contract evolution, incident ownership, operating access, documentation and exit help. Availability, staffing, support coverage and fees need current written terms.
A source diagram showing mobile widgets is not a backend architecture requirement. No fixed price, delivery window, free support period or cancellation term is inherited as an offer.
Six quality areas require visible evidence.
- Contract review: resources, methods, errors, versioning and actual consumer compatibility.
- Unit and static checks: domain rules, adapters and selected data paths, with documented limits.
- Integration and end-to-end: permitted and forbidden calls, provider failures, callbacks and reconciliation.
- Performance: real query plans, pools, caches, limits, load and recovery on representative release artefacts.
- Security: token validation, object/tenant/field/workflow rules, secrets, input/output and abuse paths.
- Operations: CI permissions, artefacts, migrations, rollback/forward-fix, backups, docs and receiver operation.
A coverage percentage, lint result or OWASP checklist is bounded evidence, not proof the API is bug-free or certified. Record open findings and acceptance rather than repeating universal delivery-quality claims.
Sixteen technology areas, selected for actual needs.
- REST:resource and HTTP contracts.
- OpenAPI:versioned documentation and contract checks.
- Node.js:runtime, packages and concurrency evidence.
- Python:runtime, validation and service lifecycle.
- GraphQL:schema, resolvers, demand and access controls.
- WebSocket:protocol, identity and reconnect state.
- PostgreSQL:constraints, transactions, queries and restore.
- Redis:cache or queue purpose, privacy and recovery.
- Kafka:event schema, ownership, offsets and duplicate handling.
- Docker:release image, runtime patches and configuration.
- GitHub Actions:reviewed tests, artefacts and release permissions.
- AWS:selected services, account responsibility and costs.
- Terraform:reviewed infrastructure, state and recovery.
- Datadog:private-data controls, alerts and ownership.
- Postman:maintained request examples and environment safety.
- Envoy:actual routing, TLS, timeouts and trust policy.
Kong and any other gateway, mesh or worker packages require their own configuration and maintenance even when not one of these sixteen stack cards.
Five stages with acceptance and dependency owners.
- Brief:consumers, records, current system, risks and confidentiality terms.
- Scope:resources, contract, policy, provider ownership, compatibility and itemised acceptance.
- Build:reviewed endpoints, domain rules, adapters, tests and demonstrable progress.
- QA:client contracts, forbidden paths, load, security, failure and recovery evidence.
- Handoff:approved release, documentation, accounts, runbooks and receiving-team operation.
Agree milestones after inspecting scope and dependencies. Provider approvals, client updates and production access can be separate work. Use current written terms for the selected scope, estimate and support.
Quote scope, provider risk and ongoing responsibility.
Obtain current itemised terms for adaptation, a custom API or continued work. Historical starting prices, MVP ranges, retainers and support periods are not current offers. Include rights, changes, acceptance, third-party charges and exit assistance.
- Number and complexity of resources, consumers, fields and workflow rules.
- Identity, permissions, credential lifecycle, audit and abuse controls.
- Provider onboarding, adapters, callbacks, uncertain outcomes and reconciliation.
- Live messages, query performance, caches, workers and capacity evidence.
- Migration, SDK/docs, infrastructure, monitoring, backup and incident ownership.
Hosting, gateway features, monitoring and per-call provider charges are separate responsibilities. A reusable base may change the scope but does not establish a fixed saving or guaranteed schedule.
Preserve consumers while changing implementations.
Inventory actual routes, clients, authentication, data ownership, error contracts and provider effects. Compare observed behaviour with specifications and identify compatibility gaps before changing the gateway or backend. Keep a clear owner for existing consumers.
Use staged routing, consumer tests, safe shadow reads and selected coexistence. Do not duplicate writes, charges or notifications while comparing systems. Plan data mappings, backfills, cutover, credential rotation, monitoring and reconciliation.
A route flag or previous image is not a complete rollback after new writes or external effects. Specify reversible steps and forward-fix procedures, test restored backups and record when old contracts may retire. No zero-downtime or zero-rework promise is inferred.
Separate the payments and open-banking scope stories.
A partner payments integration needs the provider-approved authentication method, payment requests, idempotency, callback verification, sandbox tests and reconciliation. Confirm regional eligibility, account access and operating responsibilities separately from implementing the API.
A separate London open-banking illustration includes account aggregation, payment initiation, bank adapters, ISO 20022 mapping, event streaming and Kong, Kafka and PostgreSQL with regional operating concerns. Its target-style project brief and later outcome narrative are not evidence of an actual engagement.
Do not adopt FCA or PSD2 approval, bank onboarding totals, uptime, request volume, ratings or time-to-launch as verified facts. General build intervals and the example project narrative refer to different scopes; ask for a current written plan rather than choosing one as a promise. Specialist regulatory and banking obligations need their own review.
API delivery review and handover.
The acceptance review can cover an actual specification and a running authorized demonstration of object/tenant denial, token rejection, cursor boundaries, rate-limit storage, duplicate callbacks, uncertain payment outcomes and old-client compatibility. Require clean build, release, restore and receiving-team operation as applicable.
Product patterns to consider include utility billing with metering, dunning, tax rules, customer portals and tenant reporting; security dashboards with collectors, alerts, scoring and playbooks; and B2B commerce with orders, payments, credit, distributor pricing and reconciliation. Define the exact records, permissions, integrations and failure states for the selected product. These are possible project scopes, not a client portfolio.
The written scope should name the selected implementation, source and third-party rights, account ownership, release responsibilities and support terms. Include a receiving-owner walkthrough of the agreed build, tests and recovery steps, with open items recorded before acceptance.
Eight sectors become concrete acceptance questions.
- Healthcare/life sciences:patient and appointment access, audit, retention and specialist privacy review.
- Telemedicine:participant identity, scheduling, consultation state and secure messages.
- Fintech:ledger and payment boundaries, KYC dependencies and reconciliation.
- Retail/eCommerce:stock, checkout concurrency, prices, refunds and recovery.
- Media/entertainment:billing, entitlements and content rights.
- Creator economy:paywalls, usage, payouts and moderation.
- Transportation/mobility:dispatch, location freshness, cancellation and settlement.
- Food/beverage:menu, kitchen, order and delivery state, prices and refunds.
Twelve questions before API work starts.
What do API services include?
Agree resources, policy, integrations, documentation, tests, release and receiver evidence for the actual consumers.
What does it cost?
Get current itemised scope and distinguish build, infrastructure, licenses and provider charges.
How long does it take?
Inspect consumers, data, permissions and dependencies before agreeing milestones.
Can a base platform help?
Inspect actual features, rights and custom gaps; no card proves fit or a delivery window.
REST, GraphQL or live updates?
Choose interaction models from consumer and data needs, not universal performance rankings.
Which stack is supported?
Confirm actual runtime, gateway, database, workers, versions and receiving-team skills.
What support follows?
Agree changes, compatibility, operating access, incidents, cost and exit terms in writing.
How is it secured?
Validate identity then enforce object, tenant, field and workflow rules with tested resource controls.
Can an existing API be taken over?
Audit code, consumers, secrets, contracts and effects, then plan staged repair or migration.
Can remote teams work together?
Confirm identity, language, time-zone overlap, availability and communication terms rather than inheriting office or hours claims.
Is the source ours?
Separate custom assignment from framework, base, asset and provider licenses and demonstrate handover.
Can partners use it publicly?
Define onboarding, credentials, quotas, docs, sandbox, SDKs, support and a tested version lifecycle.
Primary references for technical qualification.
Official platform, framework and API documentation checked on 17 November 2026. These support the technical checks here, not Omnistu staffing, pricing, rights, delivery or client outcomes. Recheck installed versions and configuration before implementation.
- RFC 9700: Best Current Practice for OAuth 2.0 Security - rfc-editor.org
- RFC 8725: JSON Web Token Best Current Practices - rfc-editor.org
- RFC 9745: The Deprecation HTTP Response Header Field - rfc-editor.org
- rfc-editor.org
- OpenAPI Specification v3.2.0 - spec.openapis.org (2025-09-19)
- Response Model - Return Type - FastAPI - fastapi.tiangolo.com
- Idempotent requests | Stripe API Reference - docs.stripe.com
- Receive Stripe events in your webhook endpoint | Stripe Documentation - docs.stripe.com
- RFC 9110: HTTP Semantics - rfc-editor.org
- REST Security - OWASP Cheat Sheet Series - cheatsheetseries.owasp.org
- Guidelines.md - github.com
- PostgreSQL: Documentation: 18: 7.6.Β LIMIT and OFFSET - postgresql.org
- PostgreSQL: Documentation: 18: 13.2.Β Transaction Isolation - postgresql.org
- Rate Limiting Plugin - developer.konghq.com
- FastAPI OAuth2 scopes
Bring the domain, dependencies and receiving-team needs.
Describe the records, users, permitted actions, integrations, existing code and operating constraints. Agree base/custom boundaries, acceptance evidence, current quote and handover before implementation.
Discuss API requirements β