huncode/progcode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revise September 2021 API versioning articles
Build and deploy / deploy (push) Successful in 14s
Details

Browse Source
This commit is contained in:
huncode
2026-07-31 13:06:48 +03:00
parent 35769c4149
commit 8e078b92ea
7 changed files with 960 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web/public/assets/editorial/2021/api-versioning-compatibility-2021.svg
+53
View File
@@ -0,0 +1,53 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 375 680" role="img" aria-labelledby="title desc">
<title id="title">Матрица совместимости двух клиентов API</title>
<desc id="desc">В левой части response проверки для v1 и v2, в правой request проверки для current service. Additive поле проходит, удаление обязательного поля и смена семантики отклоняются.</desc>
<rect width="375" height="680" fill="#111827" rx="20"/>
<text x="25" y="40" fill="#f9fafb" font-family="Arial, sans-serif" font-size="18" font-weight="700">Совместимость API: reader и поток</text>
<text x="25" y="63" fill="#9ca3af" font-family="Arial, sans-serif" font-size="11">Schema описывает форму; test проверяет ожидаемое поведение.</text>
<rect x="22" y="90" width="331" height="38" rx="8" fill="#1f2937"/>
<text x="37" y="115" fill="#e5e7eb" font-family="Arial, sans-serif" font-size="13" font-weight="700">response → client</text>
<text x="225" y="115" fill="#e5e7eb" font-family="Arial, sans-serif" font-size="12" font-weight="700">v1</text>
<text x="290" y="115" fill="#e5e7eb" font-family="Arial, sans-serif" font-size="12" font-weight="700">v2</text>
<text x="37" y="159" fill="#d1d5db" font-family="Arial, sans-serif" font-size="11">+ optional deliveryWindow</text>
<rect x="211" y="140" width="50" height="31" rx="7" fill="#065f46"/>
<text x="222" y="160" fill="#d1fae5" font-family="Arial, sans-serif" font-size="11" font-weight="700">PASS</text>
<rect x="278" y="140" width="50" height="31" rx="7" fill="#065f46"/>
<text x="289" y="160" fill="#d1fae5" font-family="Arial, sans-serif" font-size="11" font-weight="700">PASS</text>
<text x="37" y="205" fill="#d1d5db" font-family="Arial, sans-serif" font-size="11">− required totalMinor</text>
<rect x="211" y="186" width="50" height="31" rx="7" fill="#7f1d1d"/>
<text x="222" y="206" fill="#fee2e2" font-family="Arial, sans-serif" font-size="11" font-weight="700">STOP</text>
<rect x="278" y="186" width="50" height="31" rx="7" fill="#7f1d1d"/>
<text x="289" y="206" fill="#fee2e2" font-family="Arial, sans-serif" font-size="11" font-weight="700">STOP</text>
<text x="37" y="251" fill="#d1d5db" font-family="Arial, sans-serif" font-size="11">status changed semantics</text>
<rect x="211" y="232" width="50" height="31" rx="7" fill="#7f1d1d"/>
<text x="222" y="252" fill="#fee2e2" font-family="Arial, sans-serif" font-size="11" font-weight="700">STOP</text>
<rect x="278" y="232" width="50" height="31" rx="7" fill="#7f1d1d"/>
<text x="289" y="252" fill="#fee2e2" font-family="Arial, sans-serif" font-size="11" font-weight="700">STOP</text>
<line x1="25" y1="290" x2="350" y2="290" stroke="#374151"/>
<rect x="22" y="315" width="331" height="38" rx="8" fill="#1f2937"/>
<text x="37" y="340" fill="#e5e7eb" font-family="Arial, sans-serif" font-size="13" font-weight="700">request → current service</text>
<text x="255" y="340" fill="#e5e7eb" font-family="Arial, sans-serif" font-size="12" font-weight="700">result</text>
<text x="37" y="384" fill="#d1d5db" font-family="Arial, sans-serif" font-size="11">v1: confirmationCode</text>
<rect x="250" y="365" width="78" height="31" rx="7" fill="#065f46"/>
<text x="268" y="385" fill="#d1fae5" font-family="Arial, sans-serif" font-size="11" font-weight="700">ACCEPT</text>
<text x="37" y="430" fill="#d1d5db" font-family="Arial, sans-serif" font-size="11">v2: + deliveryPreference</text>
<rect x="250" y="411" width="78" height="31" rx="7" fill="#065f46"/>
<text x="268" y="431" fill="#d1fae5" font-family="Arial, sans-serif" font-size="11" font-weight="700">ACCEPT</text>
<text x="37" y="476" fill="#d1d5db" font-family="Arial, sans-serif" font-size="11">typo: deliveryPrefrence</text>
<rect x="250" y="457" width="78" height="31" rx="7" fill="#7f1d1d"/>
<text x="267" y="477" fill="#fee2e2" font-family="Arial, sans-serif" font-size="11" font-weight="700">REJECT</text>
<rect x="25" y="532" width="325" height="112" rx="10" fill="#172554" stroke="#3b82f6"/>
<text x="42" y="559" fill="#dbeafe" font-family="Arial, sans-serif" font-size="12" font-weight="700">Вывод для rollout</text>
<text x="42" y="584" fill="#bfdbfe" font-family="Arial, sans-serif" font-size="11">1. Новый response проверяет старый reader.</text>
<text x="42" y="604" fill="#bfdbfe" font-family="Arial, sans-serif" font-size="11">2. Новый request проверяет current service.</text>
<text x="42" y="624" fill="#bfdbfe" font-family="Arial, sans-serif" font-size="11">3. STOP удерживает legacy contract до migration.</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.7 KiB

web/public/assets/editorial/2021/api-versioning-diagnosis-2021.svg
+54
View File
@@ -0,0 +1,54 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 375 710" role="img" aria-labelledby="title desc">
<title id="title">Диагностика несовместимого изменения API</title>
<desc id="desc">Последовательность расследования: собрать доказательства, определить тип нарушения, запустить узкий contract test, затем остановить retirement или исправить request contract.</desc>
<rect width="375" height="710" fill="#172033" rx="20"/>
<text x="25" y="42" fill="#f8fafc" font-family="Arial, sans-serif" font-size="18" font-weight="700">Клиент перестал читать response</text>
<text x="25" y="64" fill="#a5b4fc" font-family="Arial, sans-serif" font-size="11">Сначала evidence, затем обратимое действие.</text>
<rect x="33" y="94" width="309" height="66" rx="10" fill="#312e81" stroke="#818cf8"/>
<text x="51" y="120" fill="#e0e7ff" font-family="Arial, sans-serif" font-size="13" font-weight="700">1 · Собрать contract evidence</text>
<text x="51" y="142" fill="#c7d2fe" font-family="Arial, sans-serif" font-size="11">endpoint · reader · sanitized request/response</text>
<path d="M188 162 L188 187" stroke="#818cf8" stroke-width="3"/>
<path d="M181 178 L188 187 L195 178" fill="none" stroke="#818cf8" stroke-width="3"/>
<rect x="33" y="192" width="309" height="58" rx="10" fill="#1e293b" stroke="#64748b"/>
<text x="51" y="217" fill="#e2e8f0" font-family="Arial, sans-serif" font-size="13" font-weight="700">2 · Назвать first failing rule</text>
<text x="51" y="238" fill="#cbd5e1" font-family="Arial, sans-serif" font-size="11">missing field · semantic change · unknown request key</text>
<path d="M188 252 L120 291" stroke="#64748b" stroke-width="3"/>
<path d="M188 252 L255 291" stroke="#64748b" stroke-width="3"/>
<rect x="31" y="300" width="151" height="92" rx="10" fill="#451a03" stroke="#fb923c"/>
<text x="47" y="326" fill="#ffedd5" font-family="Arial, sans-serif" font-size="12" font-weight="700">response break?</text>
<text x="47" y="348" fill="#fed7aa" font-family="Arial, sans-serif" font-size="10">totalMinor missing</text>
<text x="47" y="366" fill="#fed7aa" font-family="Arial, sans-serif" font-size="10">или status сменил смысл</text>
<rect x="193" y="300" width="151" height="92" rx="10" fill="#164e63" stroke="#22d3ee"/>
<text x="209" y="326" fill="#cffafe" font-family="Arial, sans-serif" font-size="12" font-weight="700">request break?</text>
<text x="209" y="348" fill="#a5f3fc" font-family="Arial, sans-serif" font-size="10">unknown key / typo</text>
<text x="209" y="366" fill="#a5f3fc" font-family="Arial, sans-serif" font-size="10">absence и null спутаны</text>
<path d="M106 394 L106 429" stroke="#fb923c" stroke-width="3"/>
<path d="M269 394 L269 429" stroke="#22d3ee" stroke-width="3"/>
<path d="M99 420 L106 429 L113 420" fill="none" stroke="#fb923c" stroke-width="3"/>
<path d="M262 420 L269 429 L276 420" fill="none" stroke="#22d3ee" stroke-width="3"/>
<rect x="31" y="435" width="151" height="88" rx="10" fill="#7f1d1d" stroke="#f87171"/>
<text x="47" y="461" fill="#fee2e2" font-family="Arial, sans-serif" font-size="12" font-weight="700">v1 test FAIL</text>
<text x="47" y="483" fill="#fecaca" font-family="Arial, sans-serif" font-size="10">остановить retirement</text>
<text x="47" y="501" fill="#fecaca" font-family="Arial, sans-serif" font-size="10">сохранить legacy response</text>
<rect x="193" y="435" width="151" height="88" rx="10" fill="#0f766e" stroke="#2dd4bf"/>
<text x="209" y="461" fill="#ccfbf1" font-family="Arial, sans-serif" font-size="12" font-weight="700">validator FAIL</text>
<text x="209" y="483" fill="#99f6e4" font-family="Arial, sans-serif" font-size="10">вернуть явный reject</text>
<text x="209" y="501" fill="#99f6e4" font-family="Arial, sans-serif" font-size="10">исправить contract sample</text>
<path d="M106 525 L188 566 L269 525" fill="none" stroke="#94a3b8" stroke-width="3"/>
<path d="M181 556 L188 566 L195 556" fill="none" stroke="#94a3b8" stroke-width="3"/>
<rect x="33" y="572" width="309" height="75" rx="10" fill="#0f172a" stroke="#94a3b8"/>
<text x="51" y="598" fill="#e2e8f0" font-family="Arial, sans-serif" font-size="13" font-weight="700">3 · Записать условие повторной попытки</text>
<text x="51" y="620" fill="#cbd5e1" font-family="Arial, sans-serif" font-size="11">new sample + reader test + owner решения</text>
<text x="51" y="638" fill="#cbd5e1" font-family="Arial, sans-serif" font-size="11">не повторять state-changing request вслепую</text>
<text x="25" y="684" fill="#94a3b8" font-family="Arial, sans-serif" font-size="10">Fixture даёт факт о contract, не доказательство реального deployment.</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.9 KiB

web/public/assets/editorial/2021/api-versioning-rollout-2021.svg
+42
View File
@@ -0,0 +1,42 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 375 720" role="img" aria-labelledby="title desc">
<title id="title">Последовательность безопасной эволюции API</title>
<desc id="desc">Пять вертикальных этапов: зафиксировать контракт, проверить additive response, проверить v2 request, отклонить removal обязательного поля и поставить retirement на паузу.</desc>
<rect width="375" height="720" fill="#0f172a" rx="20"/>
<text x="28" y="42" fill="#f8fafc" font-family="Arial, sans-serif" font-size="18" font-weight="700">Эволюция contract без прыжка</text>
<text x="28" y="65" fill="#94a3b8" font-family="Arial, sans-serif" font-size="11">Один endpoint · v1 и v2 проверяются отдельно</text>
<line x1="52" y1="117" x2="52" y2="620" stroke="#475569" stroke-width="3" stroke-dasharray="6 7"/>
<circle cx="52" cy="117" r="15" fill="#0ea5e9"/>
<text x="47" y="122" fill="#fff" font-family="Arial, sans-serif" font-size="13" font-weight="700">1</text>
<rect x="83" y="88" width="260" height="63" rx="10" fill="#172554" stroke="#38bdf8"/>
<text x="99" y="114" fill="#e0f2fe" font-family="Arial, sans-serif" font-size="13" font-weight="700">Записать базовый contract</text>
<text x="99" y="135" fill="#bae6fd" font-family="Arial, sans-serif" font-size="11">v1 request + обязательный response</text>
<circle cx="52" cy="228" r="15" fill="#10b981"/>
<text x="47" y="233" fill="#fff" font-family="Arial, sans-serif" font-size="13" font-weight="700">2</text>
<rect x="83" y="199" width="260" height="72" rx="10" fill="#052e2b" stroke="#34d399"/>
<text x="99" y="225" fill="#d1fae5" font-family="Arial, sans-serif" font-size="13" font-weight="700">Добавить deliveryWindow</text>
<text x="99" y="245" fill="#a7f3d0" font-family="Arial, sans-serif" font-size="11">v1 игнорирует key; v2 читает форму</text>
<circle cx="52" cy="350" r="15" fill="#10b981"/>
<text x="47" y="355" fill="#fff" font-family="Arial, sans-serif" font-size="13" font-weight="700">3</text>
<rect x="83" y="321" width="260" height="72" rx="10" fill="#052e2b" stroke="#34d399"/>
<text x="99" y="347" fill="#d1fae5" font-family="Arial, sans-serif" font-size="13" font-weight="700">Разрешить v2 request</text>
<text x="99" y="367" fill="#a7f3d0" font-family="Arial, sans-serif" font-size="11">absence / null / value и unknown key</text>
<circle cx="52" cy="472" r="15" fill="#f97316"/>
<text x="47" y="477" fill="#fff" font-family="Arial, sans-serif" font-size="13" font-weight="700">4</text>
<rect x="83" y="443" width="260" height="72" rx="10" fill="#431407" stroke="#fb923c"/>
<text x="99" y="469" fill="#ffedd5" font-family="Arial, sans-serif" font-size="13" font-weight="700">Candidate retirement</text>
<text x="99" y="489" fill="#fed7aa" font-family="Arial, sans-serif" font-size="11">удалён totalMinor → v1 test отклоняет</text>
<circle cx="52" cy="594" r="15" fill="#eab308"/>
<text x="47" y="599" fill="#1e293b" font-family="Arial, sans-serif" font-size="13" font-weight="700">5</text>
<rect x="83" y="565" width="260" height="72" rx="10" fill="#422006" stroke="#facc15"/>
<text x="99" y="591" fill="#fef9c3" font-family="Arial, sans-serif" font-size="13" font-weight="700">Пауза до изменения</text>
<text x="99" y="611" fill="#fde68a" font-family="Arial, sans-serif" font-size="11">legacy response сохранён; условие записано</text>
<rect x="28" y="666" width="319" height="31" rx="8" fill="#1e293b"/>
<text x="43" y="686" fill="#cbd5e1" font-family="Arial, sans-serif" font-size="11">Ворота — contract tests, не номер URL и не календарь.</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB