Clarificați sarcina și decizia
Acest ghid transformă pornirea rapidă a api într-un flux de lucru de operare care poate fi revizuit. Conectează deciziile de domeniu, proprietatea, dovezile și acceptarea, astfel încât rezultatul să continue să funcționeze în producție.
Începeți cu o cerere autentificată, validați contractul de răspuns și adăugați tratarea eșecului înainte de a conecta CMS.
Proces practic
- 1
Tipuri de surse de inventar, identificatori, câmpuri, locații, proprietari și stări de publicare.
- 2
Alegeți modelul de livrare dintre volum, latență, control editorial și toleranță la eșec.
- 3
Mapați înregistrarea sursă într-o înregistrare separată a versiunii de limbă cu o legătură durabilă.
- 4
Adăugați autentificare, idempotence, reîncercare, invalidare cache, logare și controale de acces.
- 5
Testează publicarea, modificările sursei, rezultatele indisponibile, derularea înapoi, operarea tastaturii și monitorizarea înainte de lansare.
Exemplu sau instrument
O pereche completă de solicitare și răspuns include autentificare, local, modul, idempotity și gestionarea erorilor. În instrument, înregistrați, de asemenea, valoarea de bază, proprietarul, decizia, dovezile, problema deschisă și data aprobării. Utilizați o pagină reală sau o tranzacție, astfel încât echipa să vadă dependențele, excepțiile și lucrările de întreținere care urmează după lansare.
| Punct de decizie | Înregistra | Criteriul de acceptare |
|---|---|---|
| Linia de bază | Starea curentă observată | Sursa și data înregistrate |
| Decizie | Opțiunea selectată și justificarea | Risc și audiență luate în considerare |
| Dovezi | Testați, documentați sau măsurați | Revizuabil și specific versiunii |
| Aprobare | Nume, rol și data | Toate criteriile obligatorii îndeplinite |
Trimiteți o cerere în formă de producție
Creați un client de integrare pe partea de server și stocați-i acreditările în managerul secret de implementare. Trimiteți UTF-8 JSON prin HTTPS cu un identificator de sursă stabil, o revizuire a sursei, un local solicitat, un mod de limbă și un corp de conținut. Adăugați o cheie de idempotity care rămâne aceeași atunci când lucrarea identică este reîncercată. Nu expuneți acreditările în codul browserului, fișierele de depozit, câmpurile CMS, capturile de ecran sau răspunsurile la erori vizibile de client.
Începeți cu o pagină de serviciu reprezentativă, dar nesensibilă. Includeți titluri, liste, link-uri și o condiție legală sau operațională, astfel încât răspunsul să exercite contractul de conținut real. Respingeți un identificator de sursă gol, o locație neacceptată, un mod necunoscut, un corp supradimensionat sau o structură defectuoasă înainte de a apela API. Setați o conexiune explicită și un timeout de răspuns și propagați un identificator de corelare în jurnalele aplicației dvs.
| Câmp de solicitare | Scop | Validare |
|---|---|---|
| sursăId | Legătură durabilă către înregistrarea CMS | Necesar, stabil, non-personal |
| sursăRevision | Detectează rezultatele obținute | Obligatoriu și imuabil pentru cerere |
| local și mod | Selectează regulile de limbă | Trebuie să fie o combinație activată |
| idempotencyKey | Face reîncercările în siguranță | Aceeași operațiune folosește aceeași cheie |
Validați contractul de răspuns complet
Tratează o stare HTTP de succes ca doar prima verificare. Validați schema de răspuns, identificatorul de rezultat, identificatorul sursă și revizuirea, localitatea, modul de limbă, starea procesării, blocurile de conținut, avertismentele și versiunea modelului sau a setului de reguli, acolo unde sunt furnizate. Valorile enumerate necunoscute și câmpurile obligatorii lipsă ar trebui să nu se închidă într-o eroare de integrare care poate fi revizuită. Păstrați avertismentele lângă schiță, deoarece pot identifica terminologia, calitatea sursei sau cerințele de revizuire manuală.
Stocați rezultatul generat ca o versiune nefinalizată separată, în loc să suprascrieți sursa aprobată. Înregistrați identificatorii de solicitare și de rezultat, setările de transformare, marcajele de timp și un hash de integritate al revizuirii sursei. Afișați o diferență pentru recenzenți și scăpați de toate rezultatele în funcție de destinație. Marcajul generat nu este de încredere până când validarea schemei, igienizarea, verificările de accesibilitate și aprobarea umană sunt finalizate.
- 1
Validați sarcina utilă de ieșire în raport cu o schemă locală.
- 2
Trimiteți cererea cu anteturi de autentificare, timeout, idempotity și corelație.
- 3
Validați starea, anteturile și corpul răspunsului în raport cu contractul fixat.
- 4
Creați o schiță CMS separată legată de revizuirea sursă exactă.
- 5
Dirijați avertismentele și diferențele în coada corectă de recenzii editoriale.
Gestionați erorile fără a duplica sau pierde munca
Reîncercați expirări, eșecuri de conexiune și limite de viteză numai atunci când operațiunea este idempotentă. Utilizați retragerea exponențială limitată cu fluctuații și respectați o întârziere de reîncercare furnizată de server. Nu reîncercați eșecurile de validare, eșecurile de autentificare sau opțiunile neacceptate până când nu se modifică configurația. Plasați operațiunile epuizate într-o coadă de scrisori moarte cu referința sursei, categoria de eroare sigură, numărul de încercări și următoarea echipă responsabilă.
Separați starea orientată către utilizator de detaliile de diagnosticare. Editorii au nevoie de stări clare, cum ar fi pus în coadă, procesare, schiță pregătită, acțiune necesară și eșuat cu un următor pas sigur. Operațiunile au nevoie de identificatori de solicitare, durată, categorie de stare și istoric de reîncercări, dar nu textul sursă complet din jurnalele obișnuite. Alertă privind rata de eroare susținută, vârsta în creștere a cozii de așteptare, eșecurile de autentificare, nepotrivirile schemei și schițele a căror revizuire sursă s-a schimbat în timpul procesării.
Fiecare operație care poate fi reîncercată are o cheie stabilă de idempotnță.
Backoff-ul este limitat și respectă instrucțiunile privind limita de rată.
Jurnalele exclud acreditările și corpurile de conținut inutile.
Articolele cu scrisoare moartă au un proprietar și o procedură de reluare.
Un rezultat învechit nu poate înlocui în tăcere o revizuire sursă mai nouă.
Demonstrați integrarea înainte de lansare
Testați solicitările valide, fiecare eroare de validare documentată, acreditările expirate și revocate, timeout-uri, limitele ratei, trimiterea dublură, finalizarea în afara comenzii, evoluția schemei, igienizarea și modificările sursei în timpul procesării. Confirmați că monitorizarea identifică fiecare defecțiune și că un operator instruit poate reda sau închide elementul fără editarea bazei de date. Rulați accesibilitatea și revizuirea editorială pe schița redată, mai degrabă decât doar răspunsul brut.
Lansare cu o autentificare restricționată, rate definite și limite de cheltuieli, tablouri de bord, proprietate de alertă și un comutator de rollback care oprește noua generație fără a afecta conținutul publicat. Fixați versiunea de contract acceptată și programați o revizuire a upgrade-ului. Înregistrarea de acceptare a producției ar trebui să includă dovezi de testare, aprobare de securitate, documentație privind fluxul de date, aprobarea recenzentului, instrucțiuni de operare și restaurarea cu succes a unui loc de muncă eșuat în mod deliberat.
Roluri, dovezi și aprobare
Mențineți generația separată de publicare. Un răspuns de succes este o schiță, nu o aprobare. Stocați identificatorul și versiunea sursei, setările de transformare, identificatorul de rezultat, starea de revizuire, aprobarea și timpul de publicare. Când sursa se schimbă, marcați versiunea lingvistică pentru revizuire în loc să înlocuiți în tăcere conținutul aprobat. Acest lucru face posibilă rollback-ul și auditul pe toate platformele.
Operațiuni și întreținere
Lucrarea nu se termină la publicare. Conectați versiunea sau configurația lingvistică la sursa acesteia, monitorizați măsurile de calitate și servicii și definiți declanșatorii de revizuire concreti. Declanșatorii includ modificări de sursă, modificări legale, noi nevoi de public, întrebări de asistență recurente, modificări tehnice și incidente. Un proprietar numit evaluează declanșatorul, deschide o nouă revizuire atunci când este necesar și înregistrează aprobarea reînnoită.
Listă de verificare pentru publicare
Integrarea folosește identificatori durabili de sursă.
Acreditările sunt stocate pe partea serverului și rotite.
Timeout, reîncercarea și comportamentul limită de rată sunt definite.
Cererile repetate sunt idempotente.
Conținutul generat intră într-o stare de revizuire.
Modificările sursei invalidează sau redeschid versiunea.
Navigarea lingvistică funcționează prin tastatură și tehnologie de asistență.
Monitorizarea acoperă eșecurile, cozile, latența și conținutul învechit.