Building a Headless SEO Content API in PHP: A Practical Guide

Why a Headless SEO API?

Most portfolio sites hard-code their blog content into templates. That works until you want an AI agent, a mobile app, or a second frontend to publish content too. A headless SEO content API separates content management from rendering: one JSON contract in, fully optimized HTML pages out.

The Architecture

The API I built exposes a small set of REST endpoints:

• GET /api/seo/health — public status check
• GET /api/seo/blogs — list with pagination and status filters
• POST /api/seo/blogs — create in draft or published status
• PUT /api/seo/blogs/{id} — update any supported field
• DELETE /api/seo/blogs/{id} — delete and regenerate the sitemap
• POST /api/seo/media — upload featured images

Authentication is a Bearer token (sklive...), stored server-side as a SHA-256 hash so the plain key is never persisted. Each key is limited to 60 requests per minute.

The 27-Field Content Contract

Every blog post follows a strict 27-field schema covering the full SEO surface: title, slug, markdown and HTML content, excerpt, meta title and description, canonical URL, focus keyword, Open Graph and Twitter Card fields, FAQ items, index directives, featured image, tags, language, and publishing status.

The contract is strict on purpose. Any POST or PUT containing an undocumented field is rejected with 422 Unprocessable Entity, and metatitle (max 60 chars) and metadescription (max 160 chars) are validated the same way. Strict contracts catch integration bugs early instead of letting bad data silently rot in the database.

Automatic SEO Rendering

The frontend never hand-writes SEO markup. From the stored fields the server generates:

• A single

  (any

  inside the body is automatically demoted to

  )

• Canonical link tags and meta robots directives
• Open Graph and Twitter Card tags with sensible fallbacks
• Valid Schema.org FAQPage JSON-LD compiled from the FAQ items array
• Article and Breadcrumb structured data

Sitemap Regeneration

The XML sitemap at /sitemap.xml syncs automatically on every publish, unpublish, and delete event, including Google image sitemap tags for posts with a featured image. Content changes reach search engines without any manual step.

Lessons Learned

1. Validate at the boundary. Length checks on meta fields belong in the API, not in every client.
2. Hash your keys. One-way SHA-256 storage means a database leak never exposes usable credentials.
3. Automate the boring SEO. Sitemaps, canonicals, and schema should be generated, never hand-maintained.
4. Keep the contract strict. A 422 today saves a debugging session tomorrow.