--- title: Avoid API Breaking Changes | daily.dev description: API breaking changes typically happen when internal data models are leaked directly to clients instead of being treated as a separate contract. The piece... canonical: https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Avoid API Breaking Changes | daily.dev og:description: API breaking changes typically happen when internal data models are leaked directly to clients instead of being treated as a separate contract. The piece... og:url: https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso og:image: https://api.daily.dev/og/posts/byXRf7ssO.png og:image:alt: Avoid API Breaking Changes og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # Avoid API Breaking Changes **[CodeOpinion](https://daily.dev/sources/codeopinion)** · [@codeopinion](https://daily.dev/codeopinion) · 9 min read · 0 upvotes · 0 comments ## Summary API breaking changes typically happen when internal data models are leaked directly to clients instead of being treated as a separate contract. The piece argues for designing API responses from the consumer's perspective (composing meaningful fields like ISBN, author objects, price with currency, and reviews) rather than mirroring database tables, so internals can evolve without breaking clients. It frames the API as an anti-corruption layer that translates between internal domain/data models and the external contract, and notes the amount of upfront design effort should depend on whether you control the clients or not. The same principles apply beyond HTTP responses to request bodies, URIs, and library/package APIs. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How can I design an API response so that changing my database schema doesn't break clients? Avoid returning your raw data model or ORM entities directly as the API response. Instead, compose a separate resource model tailored to client needs, using meaningful identifiers (like ISBN instead of an internal book ID), nested objects (price with amount and currency, author with id/name/bio), and renamed fields (published instead of date). This decouples your internal persistence structure from the public contract, letting internals evolve independently. _Developers shaping stable API contracts can find more architecture perspectives like this on daily.dev._ ### Should I add a currency field to my API's price response even if I only support one currency today? Yes, structuring price as an object with amount and currency from the start (rather than a bare number) avoids a breaking structural change later when you need to add currency support. Planning field shape ahead of actual need is a common way to give an API contract room to evolve without forcing clients to adapt to a changed response shape. _For API design tradeoffs like this one, developers keep track of practical advice on daily.dev._ ## Similar posts on daily.dev - [You can refactor everything except your API](https://daily.dev/posts/you-can-refactor-everything-except-your-api-pcwpvakuq) · The Polymathic Engineer · 15 upvotes · 1 comments - [Your “Backward-Compatible” API Change Can Still Break Every Strict Client](https://daily.dev/posts/your-backward-compatible-api-change-can-still-break-every-strict-client-b3shc1xc3) · Medium · 0 upvotes · 0 comments - [Good APIs Age Slowly](https://daily.dev/posts/good-apis-age-slowly-qqvotmrmd) · Programming Digest · 221 upvotes · 5 comments - [How to Design APIs](https://daily.dev/posts/how-to-design-apis-tq8wnikkj) · System Design Codex · 1 upvotes · 0 comments - [API Versioning Should Be Your Last Resort](https://daily.dev/posts/api-versioning-should-be-your-last-resort-vywyleewk) · Milan Jovanović · 47 upvotes · 5 comments --- Tags: [#architecture](https://daily.dev/tags/architecture), [#rest-api](https://daily.dev/tags/rest-api), [#domain-driven-design](https://daily.dev/tags/domain-driven-design) [View this post on daily.dev](https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"Avoid API Breaking Changes","url":"https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso"},"datePublished":"2026-10-04T13:08:04.252Z","dateModified":"2026-10-05T10:00:18.029Z","description":"API breaking changes typically happen when internal data models are leaked directly to clients instead of being treated as a separate contract. The piece...","image":"https://media.daily.dev/image/upload/s--CxzD6vbw--/f_auto/v1722860399/public/Placeholder%2005","thumbnailUrl":"https://media.daily.dev/image/upload/s--CxzD6vbw--/f_auto/v1722860399/public/Placeholder%2005","isAccessibleForFree":true,"articleSection":"CodeOpinion","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Person","name":"Derek Comartin","url":"https://daily.dev/codeopinion","image":"https://lh3.googleusercontent.com/a-/AOh14GgoQapb7NmLN1TZ6L-UCxkRpDZ4H7LKwud1DUZCTSI=s100","interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"EndorseAction"},"userInteractionCount":960}},"commentCount":0,"discussionUrl":"https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"architecture,rest-api,domain-driven-design","timeRequired":"PT9M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"CodeOpinion","item":"https://daily.dev/sources/codeopinion"},{"@type":"ListItem","position":3,"name":"Avoid API Breaking Changes"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/avoid-api-breaking-changes-byxrf7sso#faq","mainEntity":[{"@type":"Question","name":"How can I design an API response so that changing my database schema doesn't break clients?","acceptedAnswer":{"@type":"Answer","text":"Avoid returning your raw data model or ORM entities directly as the API response. Instead, compose a separate resource model tailored to client needs, using meaningful identifiers (like ISBN instead of an internal book ID), nested objects (price with amount and currency, author with id/name/bio), and renamed fields (published instead of date). This decouples your internal persistence structure from the public contract, letting internals evolve independently. Developers shaping stable API contracts can find more architecture perspectives like this on daily.dev."}},{"@type":"Question","name":"Should I add a currency field to my API's price response even if I only support one currency today?","acceptedAnswer":{"@type":"Answer","text":"Yes, structuring price as an object with amount and currency from the start (rather than a bare number) avoids a breaking structural change later when you need to add currency support. Planning field shape ahead of actual need is a common way to give an API contract room to evolve without forcing clients to adapt to a changed response shape. For API design tradeoffs like this one, developers keep track of practical advice on daily.dev."}}]} ```