Rehefa manimba ny API ianao raha tsy misy fampitandremana, dia manimba ny finoana ianao
TL;DR: Tokony hamerina ny API ianao mba hisorohana ny fanitsakitsahana ny mpanjifa misy anao rehefa manao fanovana.
TL;DR: Tokony hamerina ny API ianao mba hisorohana ny fanitsakitsahana ny mpanjifa misy anao rehefa manao fanovana.
Ny olana
- Ny fampiharana mpanjifa dia crashes
- Ny tsy fahombiazan'ny integration
- Ny fanitsakitsahana ny fitsipiky ny tsy fahampiana kely indrindra
- Ny fotoana
- Ny fitokisanao
- Mitaky rollbacks ny fandefasana
- Ny fotoana nandany ny fampandrosoana
- Ny faharetan'ny traikefa amin'ny mpampiasa
Ny vahaolana
- Ampiharina amin'ny semantic versioning
- Ny fametrahana ny backward compatibility
- Mamorona fampitandremana momba ny depreciation
- Mamorona ny lalana
- Ampiasao ny Content Negotiation
- Ny fametrahana ireo dikan parallel
- Manamarika ny fiovana alohan'ny
- Ampiasao ny endrika tsy tapaka
- Ny antontan-taratasy manimba ny fiovana mazava
- Ataovy azo antoka ny fametrahana ny parameters amin'ny logging
- Manandrana ny dikan-teny vaovao
- Ny fanesorana ny asa tsy tapaka taorian'ny masoandro
Ny fifanarahana
Rehefa manova ny API ianao raha tsy misy versioning tsara, dia mamorona fanovana mahery vaika izay misy fiantraikany amin'ny mpanjifa rehetra.
Manery ny mpanjifa hanatsarana ny fehezan-dalàna avy hatrany ianao na miatrika fahavoazana ao amin'ny rafitra.
Manitsakitsaka ny fifanarahana eo amin'ny mpamatsy API sy ny mpanjifa ianao.
Ny rindrambaiko maoderina dia miankina be amin'ny stability API, ary ny fametrahana fanovana tsy misy fampitandremana dia afaka mamorona fahadisoana amin'ny rafitra miankina.
Izany dia zava-dehibe kokoa amin'izao fotoana izao noho ny hatramin'izay.Maro ny IA mamorona ny vahaolana amin'ny fampiasana ny antontan-taratasy API efa misy.
Rehefa manatsara ny API ianao raha tsy mitazona ny fifanarahana miverimberina, dia mety hisy loza ianao amin'ny fametrahana ny fampiharana rehetra izay miankina amin'izany.
Izany dia miteraka tsy fandriampahalemana, fahadisoana, ary vidin'ny fanitsiana ho an'ny mpampiasa.
Matetika ny mpanjifa no manomeNy fahadisoanaamin'ny endri-javatra vaovao, saingy tsy nitsahatra ny fitondran-tena maharitra teo aloha.
Ny versioning tsara dia manome antoka ny fialan-tsasatra ary mitazona ny fiarovana ny rafitra.
Tsindrio ny code.
Ny fahadisoana
// 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;
});
Ny marina
// 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;
});
Ny famantarana
- [x] Ny fametrahana antsasaky ny automatique
Azonao atao ny mahita io fahatsapana io rehefa mahita API izay manova ny anaran'ny sehatra, manala ny sehatra, na manova ny rafitra angona raha tsy manakana ny fifanarahana mivantana.
Jereo ny fampiharana mpanjifa izay mitsahatra aorian'ny fampiroboroboana API.
Jereo ny fehezan-dalàna tsy misy ny lohateny na ny famoahana ny URL.
Manara-maso ny rakitsoratra fahadisoana ho an'ny fiantraikany haingana amin'ny tsy fahombiazan'ny mpanjifa taorian'ny famoahana.
Ny taona ️
- Ny APIs
Ny ambaratonga
- [X] Ny fifanarahana
Nahoana no tena zava-dehibe ny fihaonambe ️
Tokony hitandrina ny faharetana ianaoNy taratasyeo amin'ny fifanarahana API sy ny fanantenan'ny mpanjifa.
Rehefa manaisotra izany ianaoNy fifanarahanaamin'ny fanovana ny API tsy misy versioning, dia manitsakitsaka ny fitsipika fototra fa ny mpanjifa dia afaka miankina amin'ny fifanarahana mifanaraka.
Manorina tsy fitoviana eo amin'ny zavatra tian'ny mpanjifa hahazo ary izay manome ny API ianao.
Izany dia mandika ny fifanarahana iray amin'ny iray eo amin'ny fampanantenana API sy ny fandefasana API, izay mitarika amin'ny tsy fahombiazan'ny rafitra sy ny fahaverezan'ny fitokisana.
Amin'ny alalan'ny famoahana ny fandaharana eo amin'ny API sy ny raharaham-barotra izay maneho azy, ny mpanjifa dia tsy afaka mifandray amin'ny rafitrao amin'ny fomba azo antoka.
Ity tsy fitovian-kevitra ity dia mitarika amin'ny fahadisoana, ny fialan-tsasatra, ny tsy fitokisana ary ny traikefa ratsy amin'ny mpampiasa.
Ny taranaka
Ny famokarana AI matetika dia mamorona io fahatsapana io rehefa mangataka azy ireo hanatsarana na hanatsarana ny APIs misy anao.
Mifantoka amin'ny fanatsarana ny API izy ireo tsy mandinika ny fifanarahana amin'ny farany.
Mila manoro hevitra mazava ianao ny fitaovana AI mba hitazonana ny anaran'ny sehatra misy anao ary hanampy ny versioning rehefa manao fanovana.
Matetika izy ireo dia mankafy ny famolavolana madio mihoatra noho ny fandriampahalemana raha tsy misyNy mazavaMilaza ny zavatra hafa.
Ny famantarana
Ny solosaina AI dia afaka manatsara ity fahatsapana ity rehefa manome torolàlana mazava momba ny sehatry ny versioning API ianao.
Tokony mangataka azy ireo mba hanatanterahana ny versioning semantic, hitazona ny fifanarahana mivantana, ary hamorona lalana fialan-tsasatra ho an'ny endri-javatra voavonjy.
Manao izany ianao!
Tsarovy: Manao fahadisoana maro ny mpanampy AI
Fanoloran-teny: Manao ny API versioning mba hisorohana ny fanovana
Fanoloran-teny: Manao ny API versioning mba hisorohana ny fanovana
|
Without Proper Instructions |
With Specific Instructions |
|---|---|
Ny fanapahan-kevitra
Tokony mandrakariva mamerina ny API ianao mba hisorohana ny fiovana tsy misy fiantraikany amin'ny fampiharana mpanjifa.
Na dia avy amin'ny dikan'ny voalohany aza.
Rehefa mitazona fifanarahana maharitra amin'ny alàlan'ny versioning tsara ianao, dia mamorona fitokisana amin'ny mpanjifa API ary mamela fandrosoana tsy tapaka ny rafitrao.
Ny fiovàna dia tsy azo atao, fa tsy tokony hanimba ny mpanjifanao izy ireo.
Mandritra izany fotoana izany dia manome dikan-teny amin'ny API ianao, mandinika tsara ary mifandray amin'ny fomba mialoha mba hisorohana ny tsy ilaina.
Mifandraisa amin'izy ireo
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
Ny tsy fisian'ny
Ny voankazo dia ny tenakoNy hevitra.
Ny trosa
Sary avyNandositra an'i Giancarlo RevolledoNyTsy misy
Ny API dia mandrakizay, noho izany dia mandinika azy ireo tsara
Ny API dia mandrakizay, noho izany dia mandinika azy ireo tsara
Ny Martin Fowler.
Ity lahatsoratra ity dia ampahany amin'ny Series CodeSmell.
