API Status Communication

API Status Communication

You are designing how an API platform tells its external consumers what is happening - the status page, incident updates, public postmortems, SLA/SLO reporting, and maintenance notices. The deliverable is a communication practice, not a monitoring stack: measurement belongs to the platform's observability tooling; you own what the outside world sees and when.

Trustworthiness is the design constraint every step below serves. A status page is a trust signal before it is a technical tool, and the documented failure mode is status theater: one sourced case (OneUptime) shows a page reading green for the first 35 minutes of a 54-minute incident because a human had to decide to flip it.

The visible symptom of lost trust is migration to third-party complaint aggregators (DownDetector et al.) - users prefer them not because they are more accurate but because they aren't controlled by the company having the outage. Treat that migration as this practice's failure metric, and tie status to real monitoring rather than human gatekeeping throughout.

Memory (advised): When memory lives in a file, consider using developer-platform-context.md; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

Clarifying questions

Ask these before designing anything; each answer changes a later step. Batch them - this is a tactical design task, not a strategy interview.

1. Existing status page or greenfield? If one exists, request its URL and the full update history of the last 2-3 incidents.
2. Is status set by monitoring today, or does a human flip it? Which health checks, latency thresholds, and uptime probes already exist?
3. Who reads the page: integrating developers, business stakeholders/end customers, enterprise customers - in what mix? (see next section)
4. Are there contractual SLAs with consequences attached, and do any contracts specify a maintenance-notice floor?
5. Does the status page share infrastructure with the platform itself (same DNS, CDN, cloud account)? (drives channel redundancy in step 3)
6. In the last few incidents, how did consumers actually find out - and did any third party report the outage before the page did?
7. Deadline and effort ceiling - three sub-questions:

• By when must this practice be live?
• Is it a one-off fix after a bad incident, or a compounding trust asset you will run for years?
• What can you spend: engineering hours to wire monitoring, an on-call rotation to hold cadence, budget for per-message channels?

Question 7 exists because the channel and postmortem menus diverge sharply on effort and on how long the payoff lasts, and neither ranking in steps 3 and 5 can be picked without it.

• A hard deadline promotes the rungs hosted tooling gives you nearly free.
• A compounding-asset mandate promotes out-of-band redundancy and the deep write-up.

If your harness has persistent memory, store the practice's core decisions: component model and blend rule, escalation thresholds, channel set, postmortem-depth policy, published SLA edge cases. Later runs - a live incident, a postmortem, a maintenance notice - start from the practice instead of re-deriving it.

Reader roles

Regardless of whoever bought the product, the people reading a status page during an incident split by role, and the two roles want different pages:

• Integrating developers - want component-level technical detail: which endpoints, per-region scoping, latency numbers, timestamps, and a postmortem deep enough to trust. They wire status into their own alerting, which makes machine-readable push channels (webhook, RSS) first-class.
• Business stakeholders and end customers - want plain language: is it down, what's affected, when will it be fixed. Latency metrics read as noise to them.

Audience-tiered pages are the established pattern for API providers when the mix demands it:

• A public developer-facing page with API-level detail.
• An enterprise page behind SSO showing SLA compliance.
• Plain-language end-user messaging.

Default to one public developer-facing page and add tiers only when question 3 shows a real second audience - every extra tier is another surface to keep consistent during a live incident.

Workflow

1. Model the status vocabulary and component granularity.
2. Wire status to monitoring - the trust step.
3. Choose the channels: pull page plus push subscriptions.
4. Design the incident-lifecycle communication practice.
5. Set the postmortem policy.
6. Publish SLA/SLO reporting.
7. Set maintenance-window conventions.

Each step has a section below, in order.

1. Model statuses and components

• Use the four de facto incident-lifecycle statuses below. Subscribers already read this vocabulary (it is Statuspage's, industry-wide); a custom set costs comprehension and buys nothing.
• Investigating - alerted, looking into a potential problem.
• Identified - cause or affected component confirmed.
• Monitoring - fix deployed, being watched.
• Resolved
• Model component severity as breadth of impact, not felt severity - the single most load-bearing decision here.
• Degraded Performance: works but slow for everyone.
• Partial Outage: completely broken for a subset (e.g. one region).
• Major Outage: unavailable for everyone.
• Cap the page at four visual states (operational / degraded / partial / major, the industry green-yellow-orange-red). Five severities across many components is a matrix no reader holds in their head mid-incident.
• Aggregate the top-level page status from the worst component state, and document the blend rule you choose so it is applied consistently, not re-argued per incident.
• Choose component granularity by the user's mental model of the product, never by internal architecture - forty microservice names turn the page into noise exactly when it must be parseable. Group into a handful of consumer-recognizable components (e.g. API, dashboard, webhooks, docs) rather than one flat internal list.
• Scope regional incidents regionally: one data center down should read as a scoped partial outage, not a blanket "degraded" alarming users elsewhere - Cloudflare's page signals per-region for exactly this reason.
• Note the uptime-math consequence now: Degraded Performance conventionally counts as 0% downtime in SLA arithmetic, so a headline uptime figure can look excellent while masking real incidents. Step 6 handles the honest-reporting side of this.

2. Wire status to monitoring

• Tie page state directly to health checks, latency thresholds, and uptime data. No human gate decides whether customers "deserve to know" - that gate is what produced the 35-minute green lie.
• Auto-open an Investigating incident from the monitoring alert; humans then add substance, scope, and cadence. The human role is enrichment, never first disclosure.
• Write down your own staged escalation pipeline - the explicit rule for when an internal event becomes a public communication. Copy Cloudflare's citable staging below, set your own thresholds.

1. Events trigger alerts.
2. Some alerts become incidents of note.
3. All are triaged.
4. Some become problems.
5. "Major" problems trigger status-page updates.
6. P1 majors require a full published incident report.

• Include at least one workflow-level probe (a real multi-step user journey), not only infrastructure checks: infrastructure-green and product-broken are different claims. The sourced cautionary case (Sentry) is a retailer at perfect uptime while checkout was silently broken for a user segment.