The engineering API design philosophy decision record: why the API design model you chose determines your integration velocity ceiling and your backward compatibility failure rate

An 18-person developer tools startup had been building its API for two years. The product had grown through six engineers, each of whom had made independent decisions about how to design their assigned endpoints. The decisions were not arbitrary — each engineer had followed the conventions they considered best practice, derived from the APIs they had built or consumed at previous companies — but they had been made independently, without reference to a documented design philosophy, and they had produced an API surface that reflected six distinct prior experiences rather than a single coherent convention set. The pagination model used cursor-based pagination on five endpoints, offset-based pagination on nine endpoints, and a bespoke `page`/`per_page` model on three others, depending on which engineer had built each endpoint and when. The error response model used three different structures: one that put the error code in a top-level `error` string, one that put it in a nested `error.code` field with an `error.message` companion, and one that returned error detail in the HTTP status reason phrase. The naming convention for resource identifiers used snake_case in some endpoints and camelCase in others, with the dividing line corresponding to which year the endpoint was built. The timestamp format was ISO 8601 UTC on all endpoints except two, which returned Unix epoch integers because the engineer who built them had come from a systems background and had not considered that external consumers might have a preference about timestamp formats.

When the company launched its public API and opened developer registration, the first wave of integrators spent a disproportionate fraction of their integration time on discovery work that should not have been necessary. The discovery work was not the documentation reading that any unfamiliar API requires — it was the endpoint-by-endpoint relearning of which conventions applied where, because the documentation accurately described each endpoint's actual behavior and the actual behavior was inconsistent. A developer who had integrated the user management endpoints and built an error handler against the `error.code`/`error.message` model had built a valid assumption about those endpoints; the assumption was wrong for the billing endpoints, which used the top-level `error` string model. A developer who had implemented cursor-based pagination for the event feed endpoint had built a valid assumption about that endpoint; the assumption was wrong for the search endpoint, which used offset-based pagination. The developer support queue filled with tickets whose pattern was not "the docs are wrong" but "I followed the docs correctly and it worked for this endpoint but not for that one" — which the support team correctly diagnosed as a convention inconsistency problem but could not resolve by improving documentation, because the documentation was accurate and the inconsistency was in the API itself. The developer activation rate — the percentage of registered developers who completed a first successful API call within fourteen days of registration — was 22%. An audit of the API surface found 14 distinct convention combinations across 87 endpoints. The CTO, reviewing the audit results, recognized that none of the individual convention choices were wrong — cursor pagination, offset pagination, ISO 8601 timestamps, Unix epoch integers, nested error objects, flat error strings — each was defensible in isolation. The problem was the combination: an API surface that could not be learned, only memorized.

A 45-person B2B SaaS had built its REST API over three years to a documented design philosophy. The philosophy had been written by the head of engineering after the team's second major backward compatibility incident — a change to the error response structure that had broken fourteen integrations simultaneously — and it specified the conventions the team committed to going forward: all resource collections support pagination via `next_cursor` and `has_more` boolean fields, error responses always include an `error.code` string and an `error.message` string, all timestamps are UTC ISO 8601, resource identifiers are UUIDs in hyphenated format, HTTP verbs follow the standard REST semantics with no tunneling of actions through POST body fields. The philosophy had been followed consistently for two years, and external developers had noticed: the product's developer documentation included a "how our API works" section that accurately described the behavior of every endpoint because every endpoint followed the same conventions, and developer reviews of the integration experience consistently cited predictability as a differentiating positive.

In Q3, the engineering team shipped a bulk operations endpoint. The rationale was sound: the product managed large datasets for enterprise customers, and the customers' developers had been making thousands of individual API calls to perform operations that conceptually should be atomic. The bulk endpoint accepted an array of operations in the request body and returned an array of results. The team designing the endpoint recognized immediately that the existing error model did not fit the bulk case: the existing model assumed that the entire request either succeeded or failed, which was correct for single-resource operations but wrong for bulk operations where some items could succeed while others failed. The team made a pragmatic decision. They returned HTTP 200 for all bulk responses, regardless of individual item outcomes, with a `results` array where each item had a `success` boolean, a `data` field populated on success, and a `message` string populated on failure. The rationale was explicit in the internal discussion: the existing `error.code`/`error.message` model was designed for a different operation type and could not represent partial success without significant contortion. The decision was never reviewed against the design philosophy. The endpoint shipped in the Q3 release.

Six months after the bulk endpoint shipped, the customer success team escalated three data consistency incidents from enterprise customers. All three involved workflows that had been migrated from individual API calls to the bulk endpoint. The investigation found the same pattern in all three cases: the customer's error handling code — written against the design philosophy's `error.code`/`error.message` model — inspected the response for an `error` property at the top level and found none, because the bulk endpoint returned HTTP 200 with the `results` array. The error handler concluded the operation had succeeded. The `results` array contained failed items with `success: false` and a `message` string, but the error handler never reached the `results` array because it had already concluded the operation was successful. The developers who had written the error handling code had read the design philosophy, built their error handler correctly against the documented convention, and relied on the convention's consistency to cover the bulk endpoint as it covered every other endpoint. The convention had not covered the bulk endpoint. The three enterprise customers had been silently swallowing bulk operation failures for periods ranging from four weeks to five months. Fourteen integrators across the customer base were audited and found to have the same vulnerability. The remediation required a backward-incompatible change to the bulk endpoint — introducing an `errors` array for top-level bulk failures and an `error.code`/`error.message` structure in each failed `results` item — with a versioning flag that allowed existing consumers to migrate on a ninety-day timeline. The migration cost — engineering time to implement the new response format, customer success time to guide fourteen integrators through the update, and the three incidents' remediation work — was substantially larger than the cost of the design philosophy review that would have caught the convention divergence before the endpoint shipped.

A 67-person enterprise SaaS had a REST API design philosophy that external developers had begun to cite as one of the product's primary competitive advantages. The philosophy was comprehensive: a 45-page internal document covering resource modeling orientation, URL structure conventions, HTTP method semantics, request and response envelope models, pagination conventions, error response taxonomy, rate limiting response format, authentication token handling, versioning strategy, and the formal deprecation process. The API design review gate required all new endpoints to be reviewed by two senior engineers against the philosophy before merging to main; the review checklist had 23 items covering naming, error handling, pagination, versioning, and backward compatibility. The discipline of the review process was reflected in the API's external reputation: an independent survey of API consumers in the product's category ranked the company's API first in predictability and second in documentation quality.

When the company's data team proposed a GraphQL endpoint for complex analytics queries, the engineering leadership approved the proposal on sound technical grounds: the analytics queries required clients to request deeply nested, variably structured data from multiple resources, and the REST API's fixed-response-structure model required multiple round trips and significant over-fetching to support the same queries. GraphQL was the right tool for the use case. The decision was made by the engineering leadership with the data team and the head of product. The API design review team was not included in the decision. The GraphQL endpoint was treated as a separate API surface — which it was — and the REST API review process was not applied to it, because the review checklist had been written for REST endpoints. The GraphQL endpoint shipped in Q2 with its own documentation, its own error handling conventions (using the GraphQL-standard `errors` array rather than the REST API's `error.code`/`error.message` structure), its own authentication token scope (a new `analytics:read` scope not present in the REST API's scope taxonomy), its own rate limiting response format (a `X-RateLimit-*` header set rather than the `429` response with `retry-after` body field that the REST API used), and its own pagination model (connection-based pagination using `edges`, `nodes`, and `pageInfo` rather than the REST API's `next_cursor`/`has_more` model).

A year after the GraphQL endpoint shipped, the developer relations team ran its quarterly developer experience survey. The developer satisfaction score — which had been 4.6 out of 5.0 for the preceding four quarters — was 3.8. The open-text comments fell into two clusters. The larger cluster described inconsistency between the REST and GraphQL surfaces: developers who had been using the REST API for one to three years had extended their integrations to include the GraphQL analytics endpoint and had encountered a product that behaved differently in different places — different error handling, different authentication patterns, different pagination, different rate limiting. The second cluster described documentation confusion: the company's "how our API works" guide, which had been one of its most-cited positive features, had been updated to add a GraphQL section and now required an asterisk after every convention description — "all our endpoints use cursor pagination (except GraphQL, which uses connection-based pagination)" — and developers reported that the asterisks had eroded their confidence that the guide was authoritative for any surface. The head of engineering recognized the problem: the GraphQL endpoint was technically correct, the REST API was technically correct, and the combination was incoherent from the perspective of an external developer who expected a company's API surfaces to reflect a consistent design philosophy. The philosophy that had been the product's competitive advantage had not been abandoned — it was still enforced on the REST surface with the same rigor — but it had been contained by treating a new surface type as outside the philosophy's scope. Connect this to the engineering developer relations decision record: the developer satisfaction decline is exactly the activation-and-trust erosion pattern described in that record; the inconsistency the developers experienced was not a DevRel failure but an API governance failure, and the developer relations team — which had not been included in the GraphQL decision and had not known to update the design philosophy before the endpoint shipped — was the function responsible for diagnosing the consequence after the governance failure had already become visible in the consumer experience.

Structural properties set by the engineering API design philosophy decision

Two structural properties are determined by the founding decisions about convention consistency, breaking change taxonomy, and review gate governance. Both are invisible when the API surface is small enough to be understood through direct engineer-to-engineer communication, and visible when it has grown large enough that external developers must navigate it through documentation alone.

Property 1: Integration velocity ceiling. The integration velocity ceiling is the maximum speed at which an external developer can integrate a new endpoint — the fastest any integration can be completed regardless of developer skill or tooling quality — given the structural decisions made about convention consistency across the API surface. The ceiling is bounded by three factors. First, convention consistency: whether a developer who has integrated endpoint A can correctly build valid assumptions about endpoint B without reading endpoint B's documentation in full. A consistent API surface allows developers to amortize the discovery cost of learning conventions across every subsequent endpoint — the developer who has learned the pagination model once can apply it everywhere, the developer who has implemented the error handler once can use it for every call. An inconsistent surface does not allow this amortization: each endpoint requires independent discovery, and the transferable knowledge produced by integrating one endpoint is limited to the specific endpoint integrated. The 22% activation rate in the first story is not a documentation quality problem — the documentation was accurate — it is a convention consistency problem, where the discovery cost of endpoint-by-endpoint relearning made the activation path longer than the fourteen-day window for a significant fraction of registrants. Second, predictability under extension: whether the philosophy specifies how conventions apply to surface types the API does not yet have — bulk operations, webhooks, streaming endpoints, event subscriptions, batch imports — so that when the organization adds a new surface type, developers can locate it within the existing convention framework rather than encountering a new convention set that applies only to the new surface. The organizations that maintain predictability under extension treat new surface type additions as philosophy extension projects: they update the philosophy document before designing the new surface, document how the new surface type's conventions relate to the existing conventions, and review the new surface against the updated philosophy. Third, documentation as specification: whether the API documentation is derived from the design philosophy (which produces documentation that correctly describes the intended behavior and is accurate to the extent the implementation matches the philosophy) or from the implementation (which produces documentation that accurately describes whatever the implementation does, including convention violations). When documentation is derived from the implementation, it accurately describes an inconsistent surface — each endpoint's quirks are correctly documented — but the accurate documentation does not help developers who generalized correctly from the philosophy and received an unexpected result. Connect this to the API schema design decision record: the schema design decisions — how resources are modeled, how field names are chosen, how relationships are represented — are the lowest-level implementation of the design philosophy's naming and structure conventions; the schema and the philosophy must be designed as a coherent system, with the philosophy specifying the principles and the schema design decisions specifying how those principles apply to specific resource modeling choices, so that both are in sync when new endpoints are reviewed for convention consistency.

Property 2: Backward compatibility failure rate. The backward compatibility failure rate is the rate at which API changes break existing integrations — the proportion of API changes that require consumers to update their integration code to maintain correct behavior — determined by how rigorously the design philosophy defines what constitutes a breaking change, how consistently the review gate is enforced, and whether the organization has consumer impact visibility that allows it to assess a change's blast radius before shipping it. The rate is determined by three factors. First, breaking change taxonomy: whether the philosophy explicitly defines the full taxonomy of breaking versus non-breaking changes, including the cases that engineers systematically misjudge. The most common taxonomy failure is treating breaking changes as exclusively schema-level — removing a field, changing its type — while missing the semantic breaking changes that do not change the schema but change the behavior consumers have built assumptions on. Changing the semantics of an existing field (from exclusive to inclusive date range boundaries, from UTC to local timezone, from user-level to account-level scope) breaks integrations that were built on the original semantics without changing the schema in any way that a schema validator would detect. Adding a required field to a request body breaks integrations that do not send the field, even if the field was optional when the integration was built. Narrowing the valid range of an input field breaks integrations that were sending values at the edges of the previous range. The organizations with low backward compatibility failure rates define the taxonomy broadly enough to cover these cases, publish the taxonomy as a consumer obligation document so developers know what to expect and what to protect against, and apply the taxonomy as a review checklist item before any change to an existing endpoint ships. Second, enforcement model: whether the review gate is enforced by CI/CD tooling that automatically flags changes to existing endpoint contracts for human review, or by a social process that relies on engineers remembering to request a review for changes they believe may be breaking. The social model's failure rate is proportional to time pressure — changes that ship under deadline pressure are the changes least likely to receive a philosophy review — and to team size, because as the team grows, each engineer's familiarity with which changes require a review decreases. The second story's bulk endpoint failure occurred through a combination of both: the team was not under unusual time pressure, but the endpoint was classified as a new endpoint rather than a change to an existing endpoint, which placed it outside the review process that checked for backward compatibility — the social model's scope was defined as "changes to existing endpoints," and a new endpoint that violated the design philosophy's conventions was not a "change to an existing endpoint" even though it produced the same downstream harm. Third, consumer impact visibility: whether the organization has instrumented its API usage at the consumer level — mapping specific call patterns to specific integration identifiers — so that the impact of a proposed change can be assessed against the actual distribution of consumer behavior before the change ships. An organization that knows that a specific response field is inspected by 87% of active consumers treats a change to that field differently from an organization that knows only that the field exists in the response schema. Connect this to the API versioning strategy decision record: the versioning strategy is the mechanism through which the design philosophy manages the backward compatibility failure rate over time — the versioning model specifies how breaking changes are introduced without requiring all consumers to update simultaneously, what the support window is for each major version, and when a consumer that has not migrated will begin receiving errors rather than deprecated behavior; the design philosophy and the versioning strategy must be designed as a coherent system, with the philosophy specifying what counts as a breaking change and the versioning strategy specifying what happens when a breaking change needs to ship.

The engineering API design philosophy ADR: five sections

Section 1: API design paradigm and surface model. The paradigm and surface model specifies which API paradigm the organization has chosen — REST, GraphQL, gRPC, or a multi-paradigm approach — and what the surface model is for each paradigm: whether the REST surface is resource-oriented, operation-oriented, or domain-model-oriented; whether the GraphQL surface is a thin wrapper over the REST resource model or a separate graph; whether gRPC is used for internal services only or as an external API surface; what the relationship is between the webhook event payload model and the REST resource model. The most consequential decision in this section is not the paradigm choice itself — REST versus GraphQL is a well-characterized tradeoff with a large body of existing guidance — but the cross-paradigm consistency commitment: whether the design philosophy applies to all API surfaces the organization offers to the same set of external developers, or whether each paradigm is treated as an independent design project with its own conventions. The cross-paradigm consistency commitment is the structural decision that determines whether the third story's outcome is possible. An organization that explicitly scopes its design philosophy to all developer-facing API surfaces — and that treats adding a new surface type as a philosophy extension project — cannot produce the third story's outcome by design. An organization that scopes its design philosophy to its primary paradigm and treats secondary surfaces as independent creates the structural precondition for the third story's outcome: a new surface type ships under a different review process, with different conventions, and the cross-paradigm inconsistency becomes visible to external developers before it becomes visible internally. The paradigm section should also specify the explicit scope of what the philosophy covers and what happens when a new surface type is added: the process for extending the philosophy to cover the new surface type, the review gate that applies during the extension period, and the migration path for conventions on the new surface that conflict with conventions on existing surfaces. Connect this to the API deprecation strategy decision record: when the cross-paradigm consistency commitment requires migrating an existing surface type's conventions to match a unified philosophy, the deprecation process for the old conventions on the existing surface is governed by the deprecation strategy — the philosophy extension and the deprecation strategy must be designed in coordination so that the cross-paradigm unification does not require consumers to change behavior faster than the deprecation timeline allows.

Section 2: Naming and convention model. The naming and convention model specifies the complete set of conventions that apply to every endpoint on every surface — URL structure, naming conventions for resources and fields, HTTP method semantics, request and response envelope model, pagination model, error response model, timestamp format, identifier format, and the conventions for any surface-type-specific concerns (webhook delivery models, bulk operation result models, streaming protocol conventions). The most consequential decision in this section is not any individual convention choice — cursor versus offset pagination, snake_case versus camelCase, nested versus flat error objects — but the adoption test: whether the chosen conventions can be specified precisely enough that an unfamiliar engineer, reading the convention document without access to existing endpoints, could correctly design a new endpoint that is convention-consistent with every existing endpoint. If the conventions cannot be specified at that level of precision — if they require judgment calls that reasonable engineers make differently — they are design principles, not conventions, and they will produce convention drift over time as each engineer's judgment diverges at the cases the specification does not cover. The naming and convention model should include worked examples for each convention category: a conforming pagination implementation and a non-conforming one, a conforming error response and a non-conforming one, a conforming resource URL structure and a non-conforming one. The worked examples serve as calibration references for the review gate: a reviewer comparing a proposed endpoint against the examples can make a consistent conformance judgment even for cases the specification text does not explicitly cover. Connect this to the API schema design decision record: the schema design decisions are the lowest-level implementation of the naming and convention model; the schema and the convention model must be reviewed together when new endpoints are proposed, because a schema that follows the field naming conventions but violates the response envelope convention has violated the naming and convention model even though the naming review passed.

Section 3: Versioning and backward compatibility model. The versioning and backward compatibility model specifies the full taxonomy of breaking versus non-breaking changes, the version lifecycle (how versions are introduced, what the support window is for each version, how consumers are notified before a version is deprecated, how a consumer who has not migrated is handled after deprecation), the pre-change consumer impact assessment process, and the review gate that changes to existing API surfaces must pass before shipping. The most consequential decision in this section is the breaking change taxonomy: it must be broad enough to cover the semantic breaking changes that engineers routinely miss — not just schema removals and type changes but semantic changes, range narrowings, error code changes, field interpretation changes — or the review gate will pass breaking changes that the taxonomy does not classify as breaking. The taxonomy should be published as a consumer-facing document as well as an internal review tool: consumers who know the taxonomy can build their integrations defensively against the specific change types that may occur, and can build their monitoring to detect the change types that are classified as non-breaking but that may affect their specific integration. The pre-change consumer impact assessment should specify the instrumentation required to make assessment possible: at minimum, per-endpoint call volume by consumer identifier and, for response fields, whether the field is present in the documented schema is insufficient — the assessment needs to know whether specific consumers are inspecting specific fields in their integration code, which requires either consumer-level field usage telemetry or a documented process for consumers to register the fields they depend on. Connect this to the API versioning strategy decision record: the versioning strategy is the mechanism through which the backward compatibility model manages the transition from a version that contains a breaking change to the version consumers have migrated to; the two must be designed as a coherent system, not derived independently, because the versioning model's assumptions about consumer behavior during version transitions are only valid if the backward compatibility model has produced consumers with the integration patterns the versioning model expects.

Section 4: Contract documentation and discoverability model. The contract documentation model specifies whether the API contract — the authoritative specification of what every endpoint accepts and returns — is maintained as a source-of-truth artifact (OpenAPI specification, GraphQL schema, Protobuf definition) that the implementation is validated against, or as a generated artifact derived from the implementation after the implementation is written. The direction of derivation is the most consequential decision in this section: when the specification is the source of truth and the implementation is validated against it, convention violations in the implementation are caught before they ship, because the specification review is the convention review and the conformance check is automated. When the specification is generated from the implementation, convention violations in the implementation produce a specification that accurately describes the violation, which means the specification review cannot catch violations that the implementation already contains — the review is reviewing the violation's accurate description rather than the violation itself. The contract documentation model should also specify the changelog requirements: which changes require a changelog entry (at minimum all breaking changes and all new endpoints), what the entry format is, how existing consumers are notified of changes (email, in-API deprecation headers, developer portal notifications, versioned API release notes), and the advance notice period for breaking changes. The discoverability model should specify where the API specification lives, how consumers access it, how they subscribe to changes, and what the documentation accuracy guarantee is — the organization's commitment to the accuracy of its documentation, which should include a process for consumers to report documentation inaccuracies and a response time commitment for corrections. Connect this to the engineering developer relations decision record: the contract documentation and discoverability model is the technical foundation for the DevRel promise discipline commitment described in that record; the formal process that ensures external developer communications about API behavior are consistent with the product team's plans is only as reliable as the contract documentation model's accuracy — the DevRel team can only make accurate external commitments about API behavior if the contract documentation is current, authoritative, and shared with the DevRel team before changes ship.

Section 5: API design review model and governance. The API design review model specifies what triggers a mandatory review, what the review evaluates against, who the reviewers are, how the review is documented, and how the review gate is enforced — whether through CI/CD automation that prevents merging without review approval, through a PR requirement that the review is documented in a specific checklist format, or through a social process that relies on engineers requesting reviews for changes they identify as review-requiring. The enforcement model is the most consequential decision in this section: the social model's failure rate grows with team size and deadline pressure, which means the review gate is weakest exactly when it is most needed — during high-pressure releases when convention-violating shortcuts are most tempting. The automated enforcement model — a CI/CD check that fails when a proposed API change does not have a completed review checklist item in the PR — does not guarantee review quality, but it guarantees review coverage: every change that the trigger criteria identify as review-requiring receives a review before merging. The trigger criteria should be broader than "changes to existing endpoints" — the second story's bulk endpoint failure illustrates that a new endpoint can violate the design philosophy as consequentially as a change to an existing endpoint — and should include at minimum: all changes to existing endpoint contracts, all new endpoints on any API surface, all additions of new surface types, and all philosophy changes. The governance model should also specify the philosophy evolution process: how the design philosophy is updated when a new surface type is added, what the review process for philosophy changes is (who approves a convention change, what the process is for deprecating an existing convention, how the existing endpoints that followed the old convention are handled during the transition), and the consistency audit cadence — how frequently existing endpoints are audited for convention drift, and what the remediation process is for drift discovered in the audit. Connect this to the open-source extractor: the reasoning behind API design philosophy decisions — why a specific convention was chosen over the alternatives that were considered, what the review gate was designed to prevent, why the taxonomy classifies specific change types as breaking when the engineering team initially argued they were non-breaking — is reasoning conducted in AI chat sessions when the engineering leadership works through the design philosophy together, and it is the reasoning that is hardest to reconstruct after the engineers who conducted it have moved on. The API design philosophy decision record that preserves that reasoning allows the team to understand not just what the conventions are but why — what prior incident produced the current error response model, what the review gate was designed to catch that the previous process missed, and what would need to change for the taxonomy to require revision — rather than re-deriving those decisions at the cost of the backward compatibility incidents that produced them.

FAQ

Further reading

• API versioning strategy decision record — the versioning strategy is the mechanism through which the API design philosophy manages the backward compatibility failure rate over time; the versioning model specifies how breaking changes are introduced without requiring all consumers to update simultaneously, what the support window is for each major version, and how a consumer that has not migrated is handled after deprecation; the philosophy and the versioning strategy must be designed as a coherent system, not derived independently, because the versioning model's assumptions about consumer migration behavior are only valid if the backward compatibility model has produced consumers with the integration patterns the versioning model expects.
• API deprecation strategy decision record — when the cross-paradigm consistency commitment requires migrating an existing surface type's conventions to match a unified philosophy, the deprecation process for the old conventions on the existing surface is governed by the deprecation strategy; the philosophy extension and the deprecation strategy must be designed in coordination so that the cross-paradigm unification does not require consumers to change behavior faster than the deprecation timeline allows; the breaking change taxonomy in the design philosophy and the deprecation notice period in the deprecation strategy must be consistent with each other — the taxonomy classifies changes as breaking based on consumer impact, and the deprecation timeline must be long enough for consumers to migrate from breaking changes without service interruption.
• API schema design decision record — the schema design decisions are the lowest-level implementation of the design philosophy's naming and convention model; the schema and the convention model must be reviewed together when new endpoints are proposed, because a schema that follows the field naming conventions but violates the response envelope convention has violated the naming and convention model even though the naming review passed; the schema design record should specify whether the schema is the source of truth for the implementation or a generated artifact derived from it, because the direction of derivation determines whether convention violations in the implementation are caught before or after they ship.
• Engineering developer relations decision record — the API design philosophy's convention consistency is the technical foundation for the developer activation rate described in that record; a developer who encounters cross-surface inconsistency does not experience it as an API governance failure — they experience it as a product that behaves unpredictably, which erodes the trust that the DevRel team has built and that the activation funnel depends on; the DevRel promise discipline commitment requires a contract documentation model that keeps the DevRel team current on API changes before they ship, so that external commitments about API behavior remain consistent with what the product team is actually planning.
• Open-source extractor — the reasoning behind API design philosophy decisions — why a specific convention was chosen over the alternatives that were considered, what the review gate was designed to prevent, why the taxonomy classifies specific change types as breaking when the engineering team initially argued they were non-breaking — is reasoning conducted in AI chat sessions when the engineering leadership works through the design philosophy together, and it is the reasoning that is hardest to reconstruct after the engineers who conducted it have moved on; the API design philosophy decision record that preserves that reasoning allows the team to understand not just what the conventions are but why, and what would need to change for the taxonomy or the governance model to require revision, rather than re-deriving those decisions at the cost of the backward compatibility incidents that produced them.