Afklar opgave og beslutning
Denne vejledning gør api-hurtigstart til et arbejdsflow, der kan gennemgås. Det forbinder domænebeslutninger, ejerskab, beviser og accept, så resultatet fortsætter med at fungere i produktionen.
Start med én godkendt anmodning, valider svarkontrakten, og tilføj fejlhåndtering, før du tilslutter CMS.
Praktisk arbejdsgang
- 1
Beholdningskildetyper, identifikatorer, felter, lokaliteter, ejere og udgivelsestilstande.
- 2
Vælg leveringsmønsteret fra volumen, latens, redaktionel kontrol og fejltolerance.
- 3
Tilknyt kildeposten til en separat sprogversionspost med holdbar kobling.
- 4
Tilføj godkendelse, idempotens, forsøg igen, cache-invalidering, logning og adgangskontrol.
- 5
Testpublikation, kildeændringer, utilgængelige resultater, rollback, tastaturbetjening og overvågning før udgivelse.
Eksempel eller værktøj
Et komplet anmodnings- og svarpar inkluderer godkendelse, lokalitet, tilstand, idempotens og fejlhåndtering. I værktøjet skal du også registrere basislinje, ejer, beslutning, bevis, åbent spørgsmål og godkendelsesdato. Brug en rigtig side eller transaktion, så teamet ser afhængigheder, undtagelser og vedligeholdelsesarbejdet, der følger efter udgivelsen.
| Beslutningspunkt | Optag | Acceptkriterium |
|---|---|---|
| Baseline | Observeret nuværende tilstand | Kilde og dato registreret |
| Beslutning | Valgt mulighed og begrundelse | Risiko og publikum taget i betragtning |
| Beviser | Test, dokumenter eller mål | Gennemgåbar og versionsspecifik |
| Godkendelse | Navn, rolle og dato | Alle obligatoriske kriterier opfyldt |
Send én produktionsformet anmodning
Opret en integrationsklient på serversiden, og gem dens legitimationsoplysninger i den hemmelige implementeringsmanager. Send UTF-8 JSON over HTTPS med en stabil kilde-id, kilderevision, anmodet lokalitet, sprogtilstand og indholdstekst. Tilføj en idempotensnøgle, der forbliver den samme, når det identiske job prøves igen. Udsæt ikke legitimationsoplysninger i browserkode, lagerfiler, CMS-felter, skærmbilleder eller klient-synlige fejlsvar.
Start med en repræsentativ, men ikke-følsom serviceside. Inkluder overskrifter, lister, links og en juridisk eller operationel betingelse, så svaret udøver den reelle indholdskontrakt. Afvis en tom kilde-id, ikke-understøttet lokalitet, ukendt tilstand, overdimensioneret krop eller forkert udformet struktur, før du kalder API. Indstil en eksplicit forbindelse og svartimeout, og udbred en korrelations-id i dine applikationslogfiler.
| Anmodningsfelt | Formål | Validering |
|---|---|---|
| kilde-id | Holdbart link til CMS-posten | Påkrævet, stabil, ikke-personlig |
| kildeRevision | Registrerer forældede resultater | Påkrævet og uforanderlig for anmodningen |
| lokalitet og tilstand | Vælger sprogregler | Skal være en aktiveret kombination |
| idempotensnøgle | Gør genforsøg sikre | Samme operation bruger den samme tast |
Validere den komplette svarkontrakt
Behandl en vellykket HTTP-status som kun den første kontrol. Valider svarskemaet, resultat-id'et, kilde-id'en og revisionen, lokalitet, sprogtilstand, behandlingsstatus, indholdsblokke, advarsler og model- eller regelsætversion, hvor den er leveret. Ukendte enum-værdier og manglende obligatoriske felter skulle mislykkes lukket til en integrationsfejl, der kan gennemses. Gem advarsler ved siden af udkastet, fordi de kan identificere terminologi, kildekvalitet eller krav til manuel gennemgang.
Gem genereret output som et separat udkast til revision i stedet for at overskrive den godkendte kilde. Registrer anmodnings- og resultatidentifikatorer, transformationsindstillinger, tidsstempler og en integritetshash for kilderevisionen. Gør en forskel for korrekturlæsere og undgå alt output i henhold til dets destination. Genereret opmærkning er ikke-pålidelig input, indtil skemavalidering, sanitisering, tilgængelighedstjek og menneskelig godkendelse er fuldført.
- 1
Valider den udgående nyttelast mod et lokalt skema.
- 2
Send anmodningen med godkendelse, timeout, idempotens og korrelationsoverskrifter.
- 3
Valider status, overskrifter og svartekst i forhold til den fastgjorte kontrakt.
- 4
Opret et separat CMS-udkast knyttet til den nøjagtige kilderevision.
- 5
Rut advarsler og afvigelser ind i den korrekte redaktionelle anmeldelseskø.
Håndter fejl uden at duplikere eller miste arbejde
Prøv kun timeouts, forbindelsesfejl og hastighedsgrænser igen, når operationen er idempotent. Brug begrænset eksponentiel backoff med jitter, og respekter en server-leveret forsinkelse af genforsøg. Prøv ikke igen med valideringsfejl, godkendelsesfejl eller ikke-understøttede indstillinger, før konfigurationen ændres. Placer udtømte operationer i en dødbogstavskø med kildehenvisningen, sikker fejlkategori, antal forsøg og næste ansvarlige team.
Adskil brugervendt tilstand fra diagnostiske detaljer. Redaktører har brug for klare tilstande såsom i kø, behandling, kladde klar, handling påkrævet og mislykkedes med et sikkert næste trin. Operationer kræver anmodnings-id'er, varighed, statuskategori og genforsøgshistorik, men ikke den fulde kildetekst i almindelige logfiler. Advarsel om vedvarende fejlrate, voksende køalder, godkendelsesfejl, skemauoverensstemmelser og udkast, hvis kilderevision blev ændret under behandlingen.
Hver genforsøgsoperation har en stabil idempotensnøgle.
Backoff er begrænset og overholder instruktionerne om satsgrænser.
Logfiler udelukker legitimationsoplysninger og unødvendige indholdskroppe.
Dead-letter genstande har en ejer- og genafspilningsprocedure.
Et forældet resultat kan ikke stille erstatte en nyere kilderevision.
Bevis integrationen før frigivelse
Test gyldige anmodninger, alle dokumenterede valideringsfejl, udløbne og tilbagekaldte legitimationsoplysninger, timeouts, hastighedsgrænser, duplikatindsendelse, fuldførelse i ude af drift, skemaudvikling, sanitisering og kildeændringer under behandling. Bekræft, at overvågning identificerer hver fejl, og at en uddannet operatør kan afspille eller lukke elementet uden databaseredigering. Kør tilgængelighed og redaktionel gennemgang på det gengivede udkast i stedet for kun det rå svar.
Udgivelse med begrænset legitimationsoplysninger, definerede satser og forbrugsgrænser, dashboards, advarselsejerskab og en rollback-switch, der stopper ny generation uden at påvirke offentliggjort indhold. Fastgør den understøttede kontraktversion, og planlæg en opgraderingsgennemgang. Produktionsacceptregistreringen bør omfatte testbevis, sikkerhedsgodkendelse, dataflowdokumentation, reviewer-sign-off, betjeningsinstruktioner og vellykket gendannelse af et bevidst mislykket job.
Roller, beviser og godkendelse
Hold generation adskilt fra udgivelse. Et vellykket svar er et udkast, ikke en godkendelse. Gem kilde-id'et og -versionen, transformationsindstillinger, resultat-id'er, gennemgangstilstand, godkender og udgivelsestid. Når kilden ændres, skal du markere sprogversionen til gennemgang i stedet for lydløst at erstatte godkendt indhold. Dette gør rollback og revision mulig på tværs af platforme.
Drift og vedligeholdelse
Værket slutter ikke ved udgivelsen. Knyt sprogversionen eller konfigurationen til dens kilde, overvåg kvalitets- og servicemål, og definer konkrete gennemgangsudløsere. Triggere omfatter kildeændringer, juridiske ændringer, nye publikumsbehov, tilbagevendende supportspørgsmål, tekniske ændringer og hændelser. En navngivet ejer evaluerer udløseren, åbner en ny revision, når det er nødvendigt, og registrerer fornyet godkendelse.
Tjekliste før udgivelse
Integrationen bruger holdbare kildeidentifikatorer.
Legitimationsoplysninger gemmes på serversiden og roteres.
Timeout, genforsøg og hastighedsbegrænsningsadfærd er defineret.
Gentagne anmodninger er idempotente.
Genereret indhold går ind i en anmeldelsestilstand.
Kildeændringer ugyldiggør eller genåbner versionen.
Sprognavigation fungerer ved hjælp af tastatur og hjælpeteknologi.
Overvågning dækker fejl, køer, latens og forældet indhold.