Chapter 3: SERVICE BOUNDARIES & API DESIGN - System Design Course: Complete Production Architecture | PlayBook Library

SLIDE 15: Service Boundaries: When to Split

The Monolith vs Microservices Decision

Start With a Monolith:

Benefit	Explanation
Simple deployment	One artifact to deploy
Simple debugging	One log stream, one process
Simple transactions	Database ACID works naturally
Fast development	No network calls between components
Small team friendly	One codebase, one oncall

When to Split:

Signal	Description
Different scaling needs	Feed service needs 100x more instances than Upload service
Different deployment cadence	Auth changes weekly, Payments changes monthly
Different team ownership	Clear organizational boundary
Fault isolation needed	Payment failure should not crash Feed

SLIDE 15B: Service Boundaries: When to Split (continued)

How to Identify Service Boundaries:

CODE

#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .error-icon{fill:#552222;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .error-text{fill:#552222;stroke:#552222;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-thickness-normal{stroke-width:1px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-thickness-thick{stroke-width:3.5px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-pattern-solid{stroke-dasharray:0;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .marker{fill:#666;stroke:#666;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .marker.cross{stroke:#666;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b svg{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:16px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b p{margin:0;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .label{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";color:#000000;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .cluster-label text{fill:#333;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .cluster-label span{color:#333;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .cluster-label span p{background-color:transparent;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .label text,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b span{fill:#000000;color:#000000;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node rect,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node circle,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node ellipse,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node polygon,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node path{fill:#eee;stroke:#999;stroke-width:1px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .rough-node .label text,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node .label text,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .image-shape .label,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .icon-shape .label{text-anchor:middle;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .rough-node .label,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node .label,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .image-shape .label,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .icon-shape .label{text-align:center;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node.clickable{cursor:pointer;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .arrowheadPath{fill:#333333;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edgePath .path{stroke:#666;stroke-width:1px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .flowchart-link{stroke:#666;fill:none;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edgeLabel{background-color:white;text-align:center;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edgeLabel p{background-color:white;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .cluster text{fill:#333;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .cluster span{color:#333;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b rect.text{fill:none;stroke-width:0;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .icon-shape,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .image-shape{background-color:white;text-align:center;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .icon-shape p,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .image-shape p{background-color:white;padding:2px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .icon-shape .label rect,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b .node .neo-node{stroke:#999;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node rect,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].cluster rect,#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node polygon{stroke:url(#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].swimlane.cluster rect{filter:none;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node path{stroke:url(#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b-gradient);stroke-width:1px;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node circle{stroke:url(#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].node circle .state-start{fill:#000000;}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].icon-shape .icon{fill:url(#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b [data-look="neo"].icon-shape .icon-neo path{stroke:url(#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4dc0fa6d-60f3-4f57-a8d0-911cc612d37b :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}MonolithIdentify DomainsDraw Data BoundariesVerify Team AlignmentExtract Service

Domain Identification Questions:

Question	Good Split	Bad Split
Does this have its own data?	User Service owns users table	Service shares tables with others
Does this have clear API?	POST /users, GET /users/{id}	Internal function calls
Can different team own this?	Auth team owns Auth service	Single engineer owns 5 services
Does this scale differently?	Search needs more compute	Same load as rest of system

Anti-Pattern: Splitting Too Early

Premature microservices add network latency, operational overhead, and debugging complexity. Split when you feel pain, not when you predict pain.

SLIDE 16: Service Boundaries: API Contracts

Defining Contracts Between Services

What a Contract Includes:

Element	Description	Example
Endpoint	URL path and method	GET /v1/users/{id}
Request Schema	Required and optional fields	{ “email”: string, “name”: string }
Response Schema	Success and error formats	{ “user”: {…}, “error”: {…} }
SLA	Latency and availability	P99 < 100ms, 99.9% uptime
Rate Limits	Requests per second	1000 RPS per client
Versioning	How breaking changes are handled	URL versioning /v1/, /v2/

Contract Example:

CODE

Service: User Service
Endpoint: GET /v1/users/{user_id}
Owner: Identity Team
SLA: P99 < 50ms, 99.99% availability
Rate Limit: 10,000 RPS

Request:
  Path Parameter: user_id (required, integer)
  Header: Authorization: Bearer {token}

Response (200 OK):
  {
    "user_id": 12345,
    "username": "mukul",
    "email": "mukul@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }

Response (404 Not Found):
  {
    "error": "user_not_found",
    "message": "User with ID 12345 does not exist"
  }

SLIDE 16B: Service Boundaries: API Contracts (continued)

Contract Testing:

CODE

#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .error-icon{fill:#552222;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .error-text{fill:#552222;stroke:#552222;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-thickness-normal{stroke-width:1px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .marker{fill:#666;stroke:#666;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .marker.cross{stroke:#666;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 svg{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:16px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 p{margin:0;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .label{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";color:#000000;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .cluster-label text{fill:#333;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .cluster-label span{color:#333;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .cluster-label span p{background-color:transparent;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .label text,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 span{fill:#000000;color:#000000;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node rect,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node circle,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node ellipse,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node polygon,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node path{fill:#eee;stroke:#999;stroke-width:1px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .rough-node .label text,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node .label text,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .image-shape .label,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .icon-shape .label{text-anchor:middle;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .rough-node .label,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node .label,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .image-shape .label,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .icon-shape .label{text-align:center;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node.clickable{cursor:pointer;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .arrowheadPath{fill:#333333;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edgePath .path{stroke:#666;stroke-width:1px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .flowchart-link{stroke:#666;fill:none;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edgeLabel{background-color:white;text-align:center;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edgeLabel p{background-color:white;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .cluster text{fill:#333;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .cluster span{color:#333;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 rect.text{fill:none;stroke-width:0;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .icon-shape,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .image-shape{background-color:white;text-align:center;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .icon-shape p,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .image-shape p{background-color:white;padding:2px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .icon-shape .label rect,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 .node .neo-node{stroke:#999;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node rect,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].cluster rect,#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node polygon{stroke:url(#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].swimlane.cluster rect{filter:none;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node path{stroke:url(#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6-gradient);stroke-width:1px;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node circle{stroke:url(#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].node circle .state-start{fill:#000000;}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].icon-shape .icon{fill:url(#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 [data-look="neo"].icon-shape .icon-neo path{stroke:url(#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-4b30fad6-a5eb-4cda-86e3-644152145bb6 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}Provider ServiceContract DefinitionConsumer ServiceProvider TestsConsumer TestsContract Verified

Why Contracts Matter:

Without Contracts	With Contracts
Provider changes field name	Contract test fails before deploy
Consumer assumes field exists	Contract documents all fields
Breaking change in production	Breaking change caught in CI
Blame game during incident	Clear ownership and expectations

Production Practice:
Every service boundary needs a documented contract. Changes to contracts require version bump and migration period.

SLIDE 17: Service Boundaries: Versioning

How to Handle Breaking Changes

Versioning Strategies:

Strategy	URL	Header	Pros	Cons
URL Versioning	/v1/users, /v2/users	None	Explicit, easy to route	URL pollution
Header Versioning	/users	Accept-Version: v1	Clean URLs	Hidden, easy to miss
Query Param	/users?version=1	None	Flexible	Easy to forget

Recommendation: URL Versioning

CODE

/v1/users  - Current stable version
/v2/users  - New version with breaking changes

Explicit, visible, easy to route at load balancer level.

SLIDE 17B: Service Boundaries: Versioning (continued)

Managing Version Lifecycle:

CODE

#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .error-icon{fill:#552222;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .error-text{fill:#552222;stroke:#552222;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-thickness-normal{stroke-width:1px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-thickness-thick{stroke-width:3.5px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-pattern-solid{stroke-dasharray:0;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .marker{fill:#666;stroke:#666;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .marker.cross{stroke:#666;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa svg{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:16px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa p{margin:0;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .label{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";color:#000000;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .cluster-label text{fill:#333;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .cluster-label span{color:#333;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .cluster-label span p{background-color:transparent;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .label text,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa span{fill:#000000;color:#000000;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node rect,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node circle,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node ellipse,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node polygon,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node path{fill:#eee;stroke:#999;stroke-width:1px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .rough-node .label text,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node .label text,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .image-shape .label,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .icon-shape .label{text-anchor:middle;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .rough-node .label,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node .label,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .image-shape .label,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .icon-shape .label{text-align:center;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node.clickable{cursor:pointer;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .arrowheadPath{fill:#333333;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edgePath .path{stroke:#666;stroke-width:1px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .flowchart-link{stroke:#666;fill:none;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edgeLabel{background-color:white;text-align:center;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edgeLabel p{background-color:white;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .cluster text{fill:#333;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .cluster span{color:#333;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Display","Segoe UI",Helvetica,"Apple Color Emoji","Noto Sans Arabic","Noto Sans Hebrew",Arial,sans-serif,"Segoe UI Emoji","Segoe UI Symbol";font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa rect.text{fill:none;stroke-width:0;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .icon-shape,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .image-shape{background-color:white;text-align:center;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .icon-shape p,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .image-shape p{background-color:white;padding:2px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .icon-shape .label rect,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa .node .neo-node{stroke:#999;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node rect,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].cluster rect,#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node polygon{stroke:url(#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].swimlane.cluster rect{filter:none;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node path{stroke:url(#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa-gradient);stroke-width:1px;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node circle{stroke:url(#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].node circle .state-start{fill:#000000;}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].icon-shape .icon{fill:url(#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa [data-look="neo"].icon-shape .icon-neo path{stroke:url(#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#mermaid-a2200f82-9e68-4edf-84b4-de7521d5a2fa :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}v1 Currentv2 Releasedv1 Deprecatedv1 Sunsetv1 Removed

Version Lifecycle Phases:

Phase	Duration	What Happens
Current	Ongoing	Active development, full support
Deprecated	3-6 months	No new features, security fixes only
Sunset	1-3 months	Warning logs, migration reminders
Removed	Final	410 Gone response, clients must migrate

Deprecation Communication:

CODE

Response Header (during Deprecated phase):
  Deprecation: true
  Sunset: Sat, 01 Jul 2025 00:00:00 GMT
  Link: </v2/users>; rel="successor-version"

Log Warning:
  "Client X is using deprecated v1 API. Migration required by 2025-07-01."

SLIDE 18: Service Boundaries: Backward Compatibility

Rules for Non-Breaking Changes

Safe Changes (Backward Compatible):

Change Type	Example	Why Safe
Add optional field to request	Add “nickname” field	Old clients do not send it, still works
Add field to response	Add “updated_at” field	Old clients ignore unknown fields
Add new endpoint	Add GET /v1/users/{id}/posts	Does not affect existing endpoints
Widen accepted values	Accept “email” OR “phone”	Old clients sending email still work

Breaking Changes (Require Version Bump):

Change Type	Example	Why Breaking
Remove field from response	Remove “email” field	Old clients expecting it will break
Rename field	“user_name” to “username”	Old clients looking for wrong field
Change field type	“age”: string to “age”: int	Parsing breaks
Add required field to request	Require “phone” field	Old clients do not send it
Change URL structure	/users/{id} to /accounts/{id}	Old clients call wrong URL

SLIDE 18B: Service Boundaries: Backward Compatibility (continued)

The Expand-Contract Pattern:

For migrating field names without breaking clients:

Phase 1: Expand (Add new field, keep old)

CODE

{
  "user_name": "mukul",
  "username": "mukul"
}

Both fields returned. Old clients use user_name, new clients use username.

Phase 2: Migrate (Update all clients)

All clients updated to use “username” field.

Phase 3: Contract (Remove old field)

CODE

{
  "username": "mukul"
}

Old field removed after all clients migrated.

Timeline:
Expand (Week 1) -> Migrate (Weeks 2-4) -> Contract (Week 5)