Road Map
Providing visibility as far into the future as possible is a common trait of successful APIs. Maintaining, publishing, and consistently communicating around a road map helps bring alignment between API producer and consumers, providing an essential building block for managing change across any platform.
Also known as: Roadmap, Product Roadmap, Upcoming
Example
Standards
- schema.org schema.org CreativeWork
- IETF RFC 8594 — Sunset HTTP Header
- IANA IANA Link Relation — deprecation
- OAI OpenAPI Specification — deprecated flag
HTTP Headers
| Header | Direction | Spec | Description |
|---|---|---|---|
Sunset |
response | RFC 8594 | HTTP-date when the resource will become unresponsive — a roadmap signal at the protocol level. |
Deprecation |
response | draft-ietf-httpapi-deprecation-header | Indicates a resource is deprecated, often paired with a roadmap link. |
OpenAPI Expression
-
paths.*.deprecated(OpenAPI 3.x) — Operation-level deprecation flag — roadmap items often correspond to operations being deprecated. -
info.x-roadmap(Vendor extension (no formal spec)) — Some providers expose a roadmap URL via an x- extension.
Link Relations
deprecation— IANA (registered alongside the Deprecation header work)sunset— RFC 8594
Governance Rules
oas-operation-deprecated(Spectral (custom)) — Deprecated operations should link to roadmap or migration guidance.
Risk & Compliance
Security: Public roadmaps can leak competitive intent or signal future attack surface (e.g., upcoming beta endpoints). Most providers publish themes and quarters rather than dated commitments.
Tools
- ProductBoard — Roadmap management
- Aha! — Roadmap management
- GitHub Projects — Public roadmap board
- Linear — Issue / roadmap tool
- Canny — Public roadmap + feedback
Suggested Metrics
roadmap_items_shipped_per_quarter— Count of public roadmap items moved to released state per quarter.roadmap_slip_rate— Share of items that miss their stated quarter or window.feedback_to_roadmap_ratio— Share of inbound feature requests that result in a public roadmap entry.
Example Implementations
- GitHub — Public roadmap maintained as a GitHub Projects board.
- Stripe — Versioned API changelog plus targeted previews instead of a long-horizon roadmap.
- Twilio — Product changelogs and deprecation notices feed roadmap visibility.
Related Properties
Tags
- SDKs