Förtydliga uppgiften och beslutet
Den här guiden förvandlar snabbstart av api till ett arbetsflöde som går att granska. Det kopplar samman domänbeslut, ägande, bevis och acceptans så att resultatet fortsätter att fungera i produktionen.
Börja med en autentiserad begäran, validera svarskontraktet och lägg till felhantering innan du ansluter CMS.
Praktiskt arbetsflöde
- 1
Källtyper, identifierare, fält, lokaler, ägare och publiceringstillstånd.
- 2
Välj leveransmönster från volym, latens, redaktionell kontroll och feltolerans.
- 3
Mappa källposten till en separat språkversionspost med hållbar länkning.
- 4
Lägg till autentisering, idempotens, försök igen, cache-ogiltigförklaring, loggning och åtkomstkontroller.
- 5
Testpublicering, källändringar, otillgängliga resultat, återställning, tangentbordsdrift och övervakning före release.
Exempel eller verktyg
Ett komplett begäran- och svarspar inkluderar autentisering, lokalitet, läge, idempotens och felhantering. I verktyget registrerar du även baslinje, ägare, beslut, bevis, öppen fråga och godkännandedatum. Använd en riktig sida eller transaktion så att teamet ser beroenden, undantag och underhållsarbetet som följer efter release.
| Beslutspunkt | Spela in | Acceptanskriterium |
|---|---|---|
| Baslinje | Observerat aktuellt tillstånd | Källa och datum registreras |
| Beslut | Valt alternativ och motivering | Risk och publik beaktas |
| Bevis | Testa, dokumentera eller mäta | Granskbar och versionsspecifik |
| Godkännande | Namn, roll och datum | Alla obligatoriska kriterier uppfyllda |
Skicka en produktionsformad förfrågan
Skapa en integreringsklient på serversidan och lagra dess autentiseringsuppgifter i distributionshemlighetshanteraren. Skicka UTF-8 JSON över HTTPS med en stabil källidentifierare, källversion, begärt språkläge, språkläge och innehållstext. Lägg till en idempotensnyckel som förblir densamma när det identiska jobbet görs om. Exponera inte autentiseringsuppgifter i webbläsarkod, arkivfiler, CMS-fält, skärmdumpar eller klientsynliga felsvar.
Börja med en representativ men okänslig servicesida. Inkludera rubriker, listor, länkar och ett juridiskt eller operativt villkor så att svaret utövar det verkliga innehållskontraktet. Avvisa en tom källidentifierare, språk som inte stöds, okänt läge, överdimensionerad kropp eller felaktig struktur innan du anropar API. Ställ in en explicit anslutning och svarstid och sprid en korrelationsidentifierare i dina programloggar.
| Fält för begäran | Ändamål | Godkännande |
|---|---|---|
| sourceId | Hållbar länk till CMS-posten | Krävs, stabil, icke-personlig |
| sourceRevision | Upptäcker inaktuella resultat | Krävs och oföränderlig för begäran |
| språk och läge | Väljer språkregler | Måste vara en aktiverad kombination |
| idempotencyKey | Gör omförsök säkra | Samma operation använder samma tangent |
Validera det fullständiga svarskontraktet
Behandla en framgångsrik HTTP-status som endast den första kontrollen. Validera svarsschemat, resultatidentifierare, källidentifierare och revision, språkläge, bearbetningsstatus, innehållsblock, varningar och modell- eller regeluppsättningsversion där den tillhandahålls. Okända uppräkningsvärden och saknade obligatoriska fält bör misslyckas med ett integreringsfel som kan granskas. Spara varningar bredvid utkastet eftersom de kan identifiera terminologi, källkvalitet eller krav på manuell granskning.
Lagra genererad utdata som ett separat utkast till revision istället för att skriva över den godkända källan. Spela in förfrågnings- och resultatidentifierare, transformationsinställningar, tidsstämplar och en integritetshash för källversionen. Gör en skillnad för granskare och undvik all utdata enligt dess destination. Genererad markering är otillförlitlig indata tills schemavalidering, sanering, tillgänglighetskontroller och mänskligt godkännande är klara.
- 1
Validera den utgående nyttolasten mot ett lokalt schema.
- 2
Skicka begäran med autentisering, timeout, idempotens och korrelationsrubriker.
- 3
Validera status, rubriker och svarstext mot det fästa kontraktet.
- 4
Skapa ett separat CMS-utkast kopplat till den exakta källrevisionen.
- 5
Kör varningar och diffar till rätt redaktionell recensionskö.
Hantera fel utan att duplicera eller förlora arbete
Försök endast med timeouts, anslutningsfel och hastighetsgränser när operationen är idempotent. Använd begränsad exponentiell backoff med jitter och respektera en fördröjning av ett nytt försök från servern. Försök inte igen valideringsfel, autentiseringsfel eller alternativ som inte stöds förrän konfigurationen ändras. Placera uttömda operationer i en dödbokstavskö med källreferens, säker felkategori, antal försök och nästa ansvariga team.
Separera användarvänligt tillstånd från diagnostisk detalj. Redaktörer behöver tydliga tillstånd som kö, bearbetning, utkast redo, åtgärd krävs och misslyckades med ett säkert nästa steg. Operationer behöver förfrågningsidentifierare, varaktighet, statuskategori och försökshistorik, men inte hela källtexten i vanliga loggar. Varning om ihållande felfrekvens, växande köålder, autentiseringsfel, schemafel och utkast vars källrevision ändrades under bearbetningen.
Varje återförsökbar operation har en stabil idempotensnyckel.
Backoff är begränsat och respekterar instruktionerna för räntegränser.
Loggar exkluderar autentiseringsuppgifter och onödiga innehållskroppar.
Föremål med döda bokstäver har en ägare och uppspelningsprocedur.
Ett inaktuellt resultat kan inte tyst ersätta en nyare källversion.
Bevisa integrationen före release
Testa giltiga förfrågningar, alla dokumenterade valideringsfel, utgångna och återkallade autentiseringsuppgifter, timeouts, hastighetsgränser, dubbletter av inlämning, slutförande i ur ordning, schemautveckling, sanering och källändringar under bearbetning. Bekräfta att övervakning identifierar varje fel och att en utbildad operatör kan spela upp eller stänga objektet utan databasredigering. Kör tillgänglighet och redaktionell granskning på det renderade utkastet snarare än bara det råa svaret.
Släpps med en begränsad referens, definierade hastighets- och utgiftsgränser, instrumentpaneler, varningsägande och en återställningsomkopplare som stoppar ny generation utan att påverka publicerat innehåll. Fäst den kontraktsversion som stöds och schemalägg en uppgraderingsgranskning. Produktionsacceptansprotokollet bör innehålla testbevis, säkerhetsgodkännande, dataflödesdokumentation, granskaresignering, bruksanvisningar och framgångsrik återställning av ett avsiktligt misslyckat jobb.
Roller, bevis och godkännande
Håll generation åtskild från publicering. Ett framgångsrikt svar är ett utkast, inte ett godkännande. Lagra källidentifierare och version, transformationsinställningar, resultatidentifierare, granskningsstatus, godkännare och publiceringstid. När källan ändras, markera språkversionen för granskning istället för att tyst ersätta godkänt innehåll. Detta gör återställning och revision möjlig över plattformar.
Drift och underhåll
Arbetet slutar inte vid publicering. Länka språkversionen eller konfigurationen till dess källa, övervaka kvalitets- och serviceåtgärder och definiera konkreta granskningsutlösare. Triggers inkluderar källändringar, juridiska ändringar, nya publikbehov, återkommande supportfrågor, tekniska förändringar och incidenter. En namngiven ägare utvärderar utlösaren, öppnar en ny revision vid behov och registrerar förnyat godkännande.
Checklista före publicering
Integrationen använder hållbara källidentifierare.
Inloggningsuppgifter lagras på serversidan och roteras.
Timeout, försök igen och hastighetsgräns-beteende definieras.
Upprepade förfrågningar är idempotenta.
Genererat innehåll går in i ett granskningsläge.
Källändringar ogiltigförklarar eller öppnar versionen igen.
Språknavigering fungerar med tangentbord och hjälpmedel.
Övervakning täcker fel, köer, latens och inaktuellt innehåll.