Uma uxhumane i-API ngaphandle kokuthunyelwe, uxhumane ukubaluleka
TL;DR: Ufuna ukubuyekeza i-API yakho ukuze ukunceda ukuchithwa kwamakhasimende eyenziwe lapho ufakele izinguquko.
TL;DR: Ufuna ukubuyekeza i-API yakho ukuze ukunceda ukuchithwa kwamakhasimende eyenziwe lapho ufakele izinguquko.
Izinzuzo 62
- Izicelo ze-client crashes
- Izinzuzo ze-Integration
- Ukuchithwa kwe-Minimum Surprise Principle
- Ukulungiselela
- Ukukhangisa
- Ukuhambisa rollbacks ezidingekayo
- isikhathi sokuthuthukiswa
- Ukuphazamiseka kwe-user experience
izixazululo 62
- Ngena ngemvume Semantic
- Ukusebenza Backward Compatibility
- Yenza izibuyekezo ze-deprecation
- Ukwenza Roadmaps
- Ukusebenzisa Imininingwane Inthanethi
- Thumela i-version parallel
- Ukubuyekeza izinguquko ngokushesha
- Ukuhlobisa izici ngokushesha
- I-Document Breaking Changes Kulula
- Ukuhlola ama-parameter eyenziwe nge-logging
- Ukuhlola ama-versions ezintsha ngokuvamile
- Ukususa ukusebenza okuhlobene emva kwe-sunset
Umhlahlandlela
Uma ukuguqulwa kwe-API ngaphandle kwe-versioning efanelekayo, uthathe izinguquko ezivamile ezivela kumakhasimende amaningi.
Ingabe utshintshe abasebenzisi ukuhlaziywa ikhodi yabo ngokushesha noma ukujabulela imiphumela yesistimu.
Ngaba ushiye i-contract ephilayo phakathi kwebhizinisi we-API ne-consumer.
I-Software yakhelwe kakhulu ku-API-stability, futhi ukulethwa kwezimpendulo ezingenalutho ngaphandle kokuthunyelwe kungenziwa ama-cascading ama-failures phakathi kwezinhlelo ezingenalutho.
Kuyinto ebalulekile kakhulu namhlanje kunemvaIzinhlelo eziningi ze-IA zibonisa izixazululo zabo ngokusebenzisa i-API yokufinyelela.
Uma usuvele i-API ngaphandle kokugcina ukuxhumana okuqhubekayo, uthatha ingozi zonke izicelo ezisebenzayo.
Lokhu kwenza ukuzinza, ukucindezeleka, futhi izixazululo ezinzima kubasebenzisi.
I-Customer ngokuvamile ibonelelaIzinzuzoizimo ezintsha, kodwa akuyona izimo ezidlulile ezivela.
I-versioning efanelekayo ibonise izinguquko ezingenalutho futhi ivimbele ukuphathwa kwekhwalithi yakho.
Sample Ikhodi
Ngena ngemvume
// user-api-v1.json - Original API response
{
"id": 317,
"name": "Mr Nimbus",
"email": "nimbus@atlantis.com",
"nationalities": "Brazilian,Canadian,Oceanic"
}
// Later changed to this without versioning:
{
"userId": 317,
"fullName": "Mr Nimbus",
"emailAddress": "nimbus@atlantis.com",
"createdAt": "2018-12-09T18:30:00Z",
"nationalities": ["Brazilian", "Canadian", "Oceanic"]
}
fetch('/api/users/317')
.then(response => response.json())
.then(user => {
// This breaks when API changes field names and data types
document.getElementById('name').textContent = user.name;
document.getElementById('email').textContent = user.email;
// This breaks when nationalities changes from string to array
document.getElementById('nationalities').textContent
= user.nationalities;
});
Ngena ngemvume
// user-api-v1.json - Version 1 (maintained)
{
"id": 317,
"name": "Mr Nimbus",
"email": "nimbus@atlantis.com",
"nationalities": "Brazilian,Canadian,Oceanic"
}
// user-api-v2.json - Version 2
// (new structure, backward compatible)
{
"id": 317,
"userId": 317,
"name": "Mr Nimbus",
"fullName": "Mr Nimbus",
"email": "nimbus@atlantis.com",
"emailAddress": "nimbus@atlantis.com",
"createdAt": "2018-12-09T18:30:00Z",
"nationalities": "Brazilian,Canadian,Oceanic"
"nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}
// user-api-v3.json - Version 3
// (new structure, backward not compatible)
{
"userId": 317,
"fullName": "Mr Nimbus",
"emailAddress": "nimbus@atlantis.com",
"createdAt": "2018-12-09T18:30:00Z",
"nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}
// client-code-versioned.js
const API_VERSION = 'v1';
fetch(`/api/${API_VERSION}/users/317`)
.then(response => response.json())
.then(user => {
document.getElementById('name').textContent = user.name;
document.getElementById('email').textContent = user.email;
// V1 handles comma-separated string
document.getElementById('nationalities').textContent
= user.nationalities;
});
// Or with content negotiation
fetch('/api/users/317', {
headers: {
'Accept': 'application/vnd.api+json;version=1'
}
})
.then(response => response.json())
.then(user => {
document.getElementById('name').textContent = user.name;
document.getElementById('email').textContent = user.email;
document.getElementById('nationalities').textContent
= user.nationalities;
});
Ukubuyekezwa
- [x] I-Semi-Automatic
Ungathola lokhu imibuzo lapho ungathola i-API eyenza i-imeyili ye-field, ukunciphisa ama-fields, noma ukuguqulwa kwezakhiwo zebhizinisi ngaphandle kokugcina ukuxhumana kwebhizinisi.
Thola izicelo ze-client ezivela ngemuva kokusebenza kwe-API.
Thola ukulayishwa kwe-version headers noma i-URL versioning schemes.
I-Monitor Error Logs ye-spikes ezivamile ze-client failures emva kwe-releases.
Usuku ️
- Imininingwane
izinga
- [x] I-Intermediate
Yintoni i-bijection iyona ebalulekile ️
You must maintain a steadyUmhlahlandlelaphakathi kwe-API yakho ne-customer expectations.
Uma ungenza lokhuUkuhlobisaUkuguqulwa kwe-API ngaphandle kokuguqulwa kwe-versioning, ungahlukile isisekelo esisodwa ukuthi amakhasimende angakwazi ukuvuselelwa ku-interface enhle.
Ukulungiselela isivumelwano phakathi kwe-customer eyenza ukufinyelela ne-API yakho.
Ngokwenza lokhu, kuvimbela ukuhanjiswa kwe-one-to-one phakathi kwamahhala we-API kanye nokuthumela kwe-API, okuholela ukuhlukanisa kwekhwalithi kanye nokukhangisa ukuhambisa.
I-API yama-model ye-real-world services. Uma ungenza ukucubungula phakathi kwe-API yakho ne-business logic elawulwa, amakhasimende angakwazi ukuxhumana ngempumelelo ne-system yakho.
Lezi zihlanganisa zihlanganisa ama-defects, i-stoptime, ukuphazamiseka kwamandla, kanye ne-user experience emangalisayo.
Imininingwane
I-AI generators ikakhulukazi inikeza lokhu imibuzo lapho usitholele ukuba "ukushintsha" noma "ukushintsha" i-API eyenziwe.
Zihlanganisa ukwenza i-API "ngcono" ngaphandle kokucubungula ukuxhumana ngokufanayo.
You must explicitly instruct AI tools to maintain existing field names and add versioning when making changes.
Okuzenzakalelayo: Zonke izakhiwo zangaphakathi zihlanganisa izakhiwo zangaphakathi.UkuhlobisaNgithanda kanjani.
Ukubuyekezwa
I-AI generators inokukwazi ukuguqulwa okuhlobene xa ukunikezela izicelo ezizodwa mayelana nezinhlelo zokusebenza ze-API.
Ingabe ufuna ukuba usebenzise i-versioning ye-semantic, ukugcinwa kwe-backward compatibility, futhi ukwakha izindlela zokudlulisela izici ezingenalutho.
Thola kwabo!
Qiniseka: I-AI Assistants ikhiqiza imiphumela eminingi
I-Suggested Prompt: Yenza i-API ye-version to prevent breaking changes
I-Suggested Prompt: Yenza i-API ye-version to prevent breaking changes
|
Without Proper Instructions |
With Specific Instructions |
|---|---|
Ukungena ngemvume
Ingabe kufanele uxhumane njalo i-API yakho ukuze akuvimbele ukuguqulwa kwezimpendulo ezikhuthaza izicelo ze-client.
Ngaphezu kokuqala yakho version.
Uma ungenza i-contracts enhle nge-versioning efanelekayo, ungenza ukuxhumana nabathengi be-API futhi ivumela ukuthuthukiswa okuhlobene kwama-system yakho.
Ukuqhathanisa izindlela ezintsha, kodwa akufanele ukuphazamiseka amakhasimende akho.
Vula njalo i-API yakho, uxhumane ngokufanele, futhi uxhumane ngokuphathelene ukunceda ukucubungula okungagunyaziwe.
https://hackernoon.com/misusing-http-status-codes-wrecks-your-api-monitoring-and-client-logic
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-iv-7sc3w8n
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxii
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxv
I-Disclaimer
I-Code Smells Is MyUmhlahlandlela.
Imininingwane
isithombeU-Giancarlo RevolledoYiniNgena ngemvume
I-APIs iyinto ebusuku, ngakho-ke ufakele ngokucacileyo
I-APIs iyinto ebusuku, ngakho-ke ufakele ngokucacileyo
U-Martin Fowler
Okuzenzakalelayo ingxenye yeCodeSmell Series.
