ב-2012, Twitter החליפה את ה-REST API הישן שלה ב-v1.1. בשבוע אחד, עשרות אלפי third-party apps הפסיקו לעבוד. הסיבה: הם שינו endpoint paths, הוסיפו authentication חובה, ושינו response format. לא היו deprecation notices מספיקים, לא הייתה backward compatibility. אפשר לאמוד את הנזק ל-Twitter ecosystem בעשרות מיליוני דולרים של value שנשרף.
API design רע הוא אחת הבעיות הכי יקרות בindustry. API שנפרסה - לא קל לשנות. Clients תלויים בה. Breaking changes שוברים integrations. זה הסיבה ש-Jeff Bezos ב-2002 כתב mandate ל-Amazon: "All teams will henceforth expose their data and functionality through service interfaces... All service interfaces, without exception, must be designed from the ground up to be externalizable." זה ה-cause הישיר לכך ש-AWS קיים כיום.
Stripe הוא הדוגמה הנגדית: API שנחשב לאחד המעוצבים הכי טוב בindustry. הם maintain backward compatibility לAPIם מ-2011 ועד היום. הם מוסיפים features בלי לשבור clients ישנים. כשצריך breaking change - הם מאפשרים ל-client לopt-in לversion חדש. ה-developer experience הזה הוא לא bonus - זה אחד הגורמים המרכזיים שStripe שולטים ב-payment processing market.
מה Stripe עושים שאחרים לא: כל API response מחזיר object version בתוך ה-response עצמו. כש-Stripe שינה את format של charge object ב-2014, הם הוסיפו version: "2014-01-31" ל-object. Client שנכתב ב-2011 מקבל תמיד response ב-format שהכיר. Client חדש ש-opt-in ל-version 2023 מקבל format חדש. ה-servicing layer שלהם שומר כמה versions במקביל ומחזיר לכל client את ה-version שהוא רשום עליו. זה complexity אדיר מצד Stripe - אבל זה מה ש-explains למה developers אוהבים לשלם דרך Stripe יותר מאחרים.