Skip to main content
    Norditco logo
    All engineering posts
    Published November 11, 2026Norditco Engineering

    A Content API in Front of WordPress: Stable Clients, Zero CMS Change

    • product
    • learn-persian
    • api
    • architecture

    Learn Persian with Sepideh already had a working content system: Sepideh publishes courses, lessons, flashcards, shorts, and downloads in WordPress, and the web and Android apps read that material. What we did not have was a stable public contract. Clients spoke WordPress REST directly (title.rendered, ACF bags, attachment ids that sometimes arrive as numbers and sometimes as objects). Every mapper lived in every client. Changing a field meant touching the CMS or every consumer.

    This post explains the Content API we put in front of that CMS: a NestJS BFF with a clean domain contract, a temporary WordPress adapter, path-based versioning on the product host, and a hard rule that the teacher’s workflow does not change. It continues the product system we described in How the web app, Android app, and Farsi TTS fit together. Here the focus is the content boundary.

    The problem we refused to ignore

    Three pressures hit at once.

    1. Client debt. Web (Next.js), Android, and a public MCP catalog each reimplemented WordPress coercion. Bugs like “short image is blank because ACF stored a media id” showed up in one surface and not another.
    2. CMS is not an API product. WordPress REST is fine as an editor backend. It is a poor long-lived contract for apps. Field names, embedded media shapes, and plugin quirks leak into UI code.
    3. Capacity. The VPS already runs the web app, WordPress, MCP, and other Norditco products. A second full Nest stack with Postgres, admin, and mail was not acceptable as the first step. See our Compose capacity decision for why every always-on process has to earn its memory.

    We needed a public content surface that clients could trust, without rewriting Sepideh’s publishing process and without standing up a new database on day one.

    Design constraints

    ConstraintDecision
    Teacher workflowZero WordPress plugin or theme edits for the API ship
    Contract ownershipNest DTOs are the long-lived API; WordPress is behind a port
    Deploy shapeLean CONTENT_ONLY process: content + health, no TypeORM/admin/mail
    HostingSame product hostname; nginx proxies only /api/v1/ and /api/docs
    CutoverOpt-in per client; WordPress remains production until each surface flips
    Future storeContentRepository port stays SQL-ready; adapter can be replaced later

    The important line is the first one. If the API required CMS surgery, it would wait forever behind editorial work. Making WordPress an implementation detail let us ship the contract first.

    System context

    Architecture diagram. Expand for a larger view with zoom.

    Nginx keeps a clean split: the Next.js app continues to own its own /api/* routes (for example the WordPress proxy used by the browser). Nest owns only the versioned content tree and Swagger. That avoids fighting Next for every path under /api.

    What the contract looks like

    Clients call paths like:

    • GET /api/v1/content/courses
    • GET /api/v1/content/lessons/:id
    • GET /api/v1/content/lessons/:id/hub
    • GET /api/v1/content/resources
    • GET /api/v1/content/flashcards
    • GET /api/v1/content/shorts
    • GET /api/v1/content/announcements
    • GET /api/v1/content/media/:id

    List responses use one pagination envelope everywhere:

    {
      "items": [],
      "meta": { "page": 1, "perPage": 20, "total": 0, "totalPages": 0 }
    }
    

    Fields are camelCase domain names: contentHtml, lessonCount, featuredImageUrl, passwordProtected. There is no title.rendered. Resource passwords are never returned; the API only says whether a resource is password-protected. Public Swagger lives at /api/docs on the same host.

    Versioning is URI-based (v1). Additive fields stay in v1. Breaking changes get a new version and leave v1 up until clients migrate.

    Architecture inside Nest

    Architecture diagram. Expand for a larger view with zoom.

    The port is the persistence boundary. Today the only implementation talks to WordPress. Tomorrow a SQL repository can sit beside it without changing controllers. That is deliberate: we refused a “temporary” passthrough that would freeze WordPress JSON as the public shape forever.

    Mappers own coercion. A concrete example is shorts: ACF often stores image_file as a media id, not a URL. The short mapper returns what it can from embedded objects; the repository then resolves numeric ids through getMedia (with cache) so list and detail responses carry real imageUrl / videoUrl values. That bug used to live in whichever client forgot to resolve attachments. Now it lives once, behind the contract.

    Lean process, same host

    The Nest boilerplate we started from assumed a full app: database, auth admin, mail, file uploads. On a memory-tight VPS that would have been an own-goal. CONTENT_ONLY=true boots a thin process: content controllers, health/ready probes, Swagger, rate-limit and CORS baselines. Ready checks whether the configured WordPress origin answers, with a short cache so a blip does not flap the probe.

    Images are built on a laptop and loaded on the VPS. Deploy promotes a staged Compose file through the same audited production gate we use for other host changes, ensures nginx locations for /api/v1/ and /api/docs, and verifies origin health. Rollback is a named Compose and nginx backup. We treat Cloudflare purge for those URLs as part of the same release surface so edge cache does not lie about health or docs after a deploy.

    Cutover without a big bang

    Flipping every client on day one would couple API maturity to app release trains. Instead each surface gets an opt-in path.

    SurfaceStrategy
    WebCONTENT_API_BASE_URL steers course/lesson/resource/flashcard services at Nest; adapters map DTOs back to the existing UI types so pages do not rewrite in the same PR
    AndroidLiving contract documents the API as a green add; base URL cutover is a separate ticket
    MCPCatalog can prefer Content API with WordPress fallback

    The web adapters are a deliberate compromise. The long-term UI should speak Nest types directly. For the first cutover, preserving WP-shaped TypeScript types keeps risk in the fetch layer. Production keeps WordPress until the env var is set and verified. That is slower than a heroic rewrite and much easier to reverse.

    What we explicitly did not do

    • Edit WordPress. No plugin, no theme patch, no custom REST controller in PHP for this ship.
    • Replace the CMS. Sepideh still publishes where she already works.
    • Stand up SQL on day one. The port is ready; the store waits until traffic and editorial needs justify it.
    • Share Redis yet. In-memory TTL is enough for a single Content API instance. Shared cache is a later scale ticket.
    • Expose raw WordPress as “v1”. Early experiments that proxied wp-json taught us that clients would depend on _links and class_list again. Those shapes are not the product contract.

    Operational lessons

    1. Path-based API on the product host beats a new subdomain when cookies, CORS, and mental model already center on one site. Restrict the proxy carefully so Next keeps its own routes.
    2. Build on the laptop, stage on the VPS. RAM-tight hosts should not compile Nest during deploys.
    3. Contract tests against golden WordPress fixtures catch mapper drift when ACF output changes. Fixtures catch blank images before production does.
    4. Health is not ready. Liveness says the process is up. Readiness says the upstream content origin is reachable.
    5. Document the living contract next to the mobile app. A GREEN add in the backend contract file stops people from assuming Nest equals wp-json.

    What comes next

    The Content API is live on the product host. Web cutover is opt-in. Mobile and MCP still default to WordPress. A shared Redis cache and an owned SQL store remain backlog until the adapter’s limits are the problem, not the clients’.

    If you maintain a CMS that is also your public API, the move we recommend is the same: put a versioned domain contract in front, keep the editor workflow untouched, and migrate clients when their release trains allow it. The CMS can stay. The leaky JSON does not have to.