Web Security & Mobile App Development

API-First Development Strategy: Synchronizing Web, Native Mobile, and Third-Party Systems

Contract-first delivery with OpenAPI and codegen, versioning policy, mobile release skew, webhook design and partner-grade governance.

Thushara SanjeewaLead Systems Architect & Media Buying Director8 min read

API-first means the contract exists before the implementation and before any consumer. The failure it prevents is specific: a web team ships a feature, mobile discovers the response shape changed, and partners find out from a support ticket. Once native apps are in the field, breaking changes are not deployable — old versions persist for months.

The objective for engineering leadership is a governed contract: machine-readable, versioned, tested against real consumers, and safe for clients you cannot force to upgrade.

Contract-First Workflow

  1. Design the schema first in OpenAPI or a GraphQL SDL, reviewed by the consumers who will call it.
  2. Generate, do not hand-write, clients. Emit typed SDKs for web, mobile and partners from the same specification so drift is impossible.
  3. Mock from the specification so front-end and mobile work starts before the backend is complete.
  4. Validate at runtime against the same schema in the gateway, rejecting unknown fields and malformed payloads.
  5. Contract-test in CI: consumer expectations verified against the provider on every build, blocking merges that break a live client.

Versioning for Un-upgradeable Clients

  • Evolve additively: new optional fields and new endpoints never break existing callers.
  • Support at least two versions concurrently with published sunset dates and deprecation headers.
  • Instrument version usage per client and per field so removal decisions are evidence-based.
  • Never repurpose a field's meaning; add a new one. Silent semantic changes are the most damaging break because they pass type checks.
  • Enforce a minimum supported app version with a graceful forced-upgrade path for security-critical changes only.

Event and Webhook Surface

Partner integrations need push, not polling. Publish versioned event types with stable identifiers, sign payloads with HMAC and a timestamp window, guarantee at-least-once delivery with exponential retry and dead-letter visibility, and document idempotent consumption keyed by event ID. Provide a replay endpoint so partners can recover from their own outages without support intervention.

Approach Comparison

ApproachConsumer safetyDelivery speedGovernance cost
Code-first, docs generated laterLow — drift is normalFast initiallyLow, high rework
Contract-first with codegenHighModerateModerate
GraphQL with schema checksHigh for first-partyFast for clientsRequires cost controls
Backend-for-frontend per channelHighFast per channelDuplication risk

Blueprint: Specification Fragment and Generated Usage

yaml
openapi: 3.1.0
info: { title: Partner API, version: 1.4.0 }
paths:
  /v1/leads:
    post:
      operationId: createLead
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, maxLength: 64 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LeadInput" }
      responses:
        "201":
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Lead" }
        "409": { description: Duplicate idempotency key }
components:
  schemas:
    LeadInput:
      type: object
      additionalProperties: false
      required: [fullName, email]
      properties:
        fullName: { type: string, minLength: 2, maxLength: 80 }
        email: { type: string, format: email }
        monthlyVolume:
          type: string
          enum: ["1k-5k", "5k-20k", "20k-100k", "100k+"]
    Lead:
      allOf:
        - $ref: "#/components/schemas/LeadInput"
        - type: object
          required: [id, createdAt]
          properties:
            id: { type: string, format: uuid }
            createdAt: { type: string, format: date-time }

additionalProperties: false plus generated clients is what keeps three consumer platforms honest over time.

Strategic Action Plan: 90 Days

  1. Days 1–12 — Publish the current truth. Reverse-engineer a specification for existing endpoints, record actual consumer usage per field and version.
  2. Days 13–30 — Establish the pipeline. Specification in version control, generated clients for web and mobile, mock server for parallel development.
  3. Days 31–50 — Gate changes. Add breaking-change detection and consumer contract tests to CI, plus runtime schema validation at the gateway.
  4. Days 51–70 — Formalise policy. Document versioning rules, deprecation windows, sunset headers and minimum supported app versions; instrument field-level usage.
  5. Days 71–90 — Ship the partner surface. Signed webhooks with retries and replay, scoped API keys with quotas, and self-service documentation generated from the specification.

Frequently Asked Questions

What makes a change breaking for native mobile clients?

Anything an installed binary cannot tolerate: removing or renaming a field, narrowing a type, adding a required request field, changing an enum value, or altering a field's meaning while keeping its name. Because old app versions remain in use for months, treat all four as prohibited within a version and add new fields or endpoints instead.

Is GraphQL inherently API-first?

The schema is a contract, so GraphQL encourages the practice, but it does not supply governance. You still need schema-change checks against recorded client operations, deprecation instrumentation, query cost limits and persisted operations for untrusted callers. Without those, a GraphQL schema drifts and becomes abusable just as a REST surface does.

How many API versions should be supported at once?

Two is the practical standard: current and previous, with a published sunset date for the older one and deprecation headers on every response. Supporting more multiplies test surface and slows delivery; supporting only one forces breaking upgrades onto mobile users who cannot upgrade immediately.

Should each client platform get its own backend endpoint?

Use a backend-for-frontend when a channel has genuinely different aggregation or payload-size needs — a mobile screen requiring one composed response instead of five calls, for example. Keep the domain logic in shared services so the BFF only composes and shapes data; duplicating business rules per channel is how platforms diverge.