Ujasněte si úkol a rozhodnutí
Tato příručka změní rychlý start rozhraní API na přehledný provozní pracovní postup. Propojuje rozhodování o doméně, vlastnictví, důkazy a přijímání, takže výsledek nadále funguje v produkci.
Začněte s jedním ověřeným požadavkem, ověřte smlouvu s odpovědí a před připojením CMS přidejte řešení selhání.
Praktický postup
- 1
Typy zdrojů inventáře, identifikátory, pole, národní prostředí, vlastníci a stavy publikace.
- 2
Vyberte vzor doručení z objemu, latence, redakční kontroly a odolnosti proti selhání.
- 3
Mapujte zdrojový záznam na samostatný záznam jazykové verze s trvalým propojením.
- 4
Přidejte ověřování, idempotency, opakování, zneplatnění mezipaměti, protokolování a řízení přístupu.
- 5
Testovací publikace, změny zdroje, nedostupné výsledky, vrácení zpět, ovládání klávesnice a monitorování před vydáním.
Příklad nebo nástroj
Kompletní dvojice požadavků a odpovědí zahrnuje autentizaci, národní prostředí, režim, idempotenci a zpracování chyb. V nástroji také zaznamenejte výchozí stav, vlastníka, rozhodnutí, důkazy, otevřený problém a datum schválení. Použijte skutečnou stránku nebo transakci, aby tým viděl závislosti, výjimky a údržbu, která následuje po vydání.
| Rozhodovací bod | Záznam | Kritérium přijetí |
|---|---|---|
| Základní linie | Pozorovaný aktuální stav | Zdroj a datum zaznamenány |
| Rozhodnutí | Vybraná možnost a zdůvodnění | Zváženo riziko a publikum |
| Důkaz | Testujte, dokumentujte nebo měřte | Kontrolovatelné a specifické pro verzi |
| Schválení | Jméno, role a datum | Splněna všechna povinná kritéria |
Pošlete jednu poptávku ve tvaru výroby
Vytvořte klienta pro integraci na straně serveru a uložte jeho pověření do správce tajných klíčů nasazení. Odesílejte UTF-8 JSON přes HTTPS se stabilním identifikátorem zdroje, revizí zdroje, požadovaným národním prostředím, jazykovým režimem a tělem obsahu. Přidejte klíč idempotence, který zůstane stejný, když se identická úloha zopakuje. Nezveřejňujte přihlašovací údaje v kódu prohlížeče, souborech úložiště, polích CMS, snímcích obrazovky nebo chybových odpovědích viditelných pro klienta.
Začněte reprezentativní, ale necitlivou stránkou služby. Zahrňte nadpisy, seznamy, odkazy a právní nebo provozní podmínky, aby odpověď uplatňovala skutečnou smlouvu o obsahu. Před voláním API odmítněte prázdný identifikátor zdroje, nepodporované národní prostředí, neznámý režim, příliš velké tělo nebo chybně tvarovanou strukturu. Nastavte explicitní časový limit připojení a odezvy a rozšiřte identifikátor korelace do protokolů vaší aplikace.
| Pole požadavku | Účel | Validace |
|---|---|---|
| sourceId | Odolné spojení se záznamem CMS | Povinný, stabilní, neosobní |
| zdrojRevize | Detekuje zastaralé výsledky | Povinné a neměnné pro požadavek |
| národní prostředí a režim | Vybírá jazyková pravidla | Musí to být povolená kombinace |
| idempotencyKey | Zajišťuje bezpečné opakování | Stejná operace používá stejný klíč |
Ověřte úplnou smlouvu o odpovědi
Úspěšný stav HTTP považujte pouze za první kontrolu. Ověřte schéma odezvy, identifikátor výsledku, identifikátor zdroje a revizi, národní prostředí, jazykový režim, stav zpracování, bloky obsahu, varování a verzi modelu nebo sady pravidel, jsou-li dodány. Neznámé hodnoty výčtu a chybějící povinná pole by se neměly zavřít do přezkoumatelné chyby integrace. Uchovávejte varování vedle konceptu, protože mohou identifikovat terminologii, kvalitu zdroje nebo požadavky na ruční kontrolu.
Uložte vygenerovaný výstup jako samostatnou revizi konceptu, nikoli přepisování schváleného zdroje. Zaznamenejte identifikátory požadavků a výsledků, nastavení transformace, časová razítka a integritu hash zdrojové revize. Renderujte rozdíl pro recenzenty a unikněte všem výstupům podle jeho cíle. Vygenerované značky jsou nedůvěryhodným vstupem, dokud není dokončeno ověření schématu, dezinfekce, kontroly přístupnosti a schválení člověkem.
- 1
Ověřte odchozí užitečné zatížení podle místního schématu.
- 2
Odešlete požadavek s autentizací, časovým limitem, idempotency a korelačními hlavičkami.
- 3
Ověřte stav, záhlaví a tělo odpovědi podle připnuté smlouvy.
- 4
Vytvořte samostatný návrh CMS spojený s přesnou zdrojovou revizí.
- 5
Směrujte varování a diffy do správné fronty redakční kontroly.
Zvládejte chyby bez duplikace nebo ztráty práce
Časové limity opakování, selhání připojení a omezení rychlosti pouze v případě, že je operace idempotentní. Použijte omezený exponenciální backoff s jitterem a respektujte serverem poskytnuté zpoždění opakování. Nepokoušejte se znovu o selhání ověření, selhání ověření nebo nepodporované možnosti, dokud se nezmění konfigurace. Umístěte vyčerpané operace do fronty nedoručených zpráv s odkazem na zdroj, kategorií bezpečné chyby, počtem pokusů a dalším odpovědným týmem.
Oddělte stav pro uživatele od podrobností diagnostiky. Editoři potřebují jasné stavy, jako je zařazení do fronty, zpracování, připravený koncept, vyžadována akce a selhání s bezpečným dalším krokem. Operace potřebují identifikátory požadavků, dobu trvání, kategorii stavu a historii opakování, ale ne úplný zdrojový text v běžných protokolech. Upozornění na trvalou chybovost, rostoucí stáří fronty, selhání ověřování, neshody schémat a koncepty, jejichž zdrojová revize se během zpracování změnila.
Každá opakovatelná operace má stabilní klíč idempotence.
Backoff je omezený a respektuje pokyny pro rychlostní limit.
Protokoly nezahrnují přihlašovací údaje a nepotřebná těla obsahu.
Položky s nedoručenou zprávou mají vlastníka a postup přehrávání.
Zastaralý výsledek nemůže tiše nahradit novější zdrojovou revizi.
Prokázat integraci před vydáním
Testujte platné požadavky, každou zdokumentovanou chybu ověření, vypršená a odvolaná pověření, časové limity, limity sazeb, duplicitní odeslání, dokončení mimo pořadí, vývoj schématu, sanitaci a změny zdroje během zpracování. Potvrďte, že monitorování identifikuje každé selhání a že vyškolený operátor může položku přehrát nebo zavřít bez úpravy databáze. Spusťte usnadnění přístupu a redakční kontrolu na vykresleném konceptu, nikoli pouze nezpracovanou odpověď.
Vydání s omezeným pověřením, definovaným limitem sazby a výdajů, řídicími panely, vlastnictvím upozornění a přepínačem vrácení, který zastaví novou generaci, aniž by to ovlivnilo publikovaný obsah. Připněte podporovanou verzi smlouvy a naplánujte kontrolu upgradu. Záznam o přijetí do výroby by měl obsahovat důkazy o zkouškách, bezpečnostní schválení, dokumentaci toku dat, odhlášení kontrolorem, provozní pokyny a úspěšnou obnovu jedné záměrně neúspěšné úlohy.
Role, důkazy a schválení
Generování uchovávejte odděleně od publikace. Úspěšná odpověď je návrh, nikoli schválení. Uložte identifikátor zdroje a verzi, nastavení transformace, identifikátor výsledku, stav recenze, schvalovatele a čas publikace. Když se zdroj změní, místo tichého nahrazování schváleného obsahu označte jazykovou verzi ke kontrole. To umožňuje rollback a audit napříč platformami.
Provoz a údržba
Publikací práce nekončí. Propojte jazykovou verzi nebo konfiguraci s jejím zdrojem, sledujte měření kvality a služeb a definujte konkrétní spouštěče kontroly. Spouštěče zahrnují změny zdroje, právní změny, nové potřeby publika, opakující se otázky podpory, technické změny a incidenty. Jmenovaný vlastník vyhodnotí spouštěč, v případě potřeby otevře novou revizi a zaznamená obnovené schválení.
Kontrolní seznam pro zveřejnění
Integrace využívá trvalé identifikátory zdroje.
Pověření se ukládají na straně serveru a střídají se.
Je definován časový limit, opakování a chování při omezení rychlosti.
Opakované žádosti jsou idempotentní.
Vygenerovaný obsah přejde do stavu recenze.
Změny zdroje zruší platnost nebo znovu otevřou verzi.
Jazyková navigace funguje pomocí klávesnice a asistenční technologie.
Monitorování pokrývá selhání, fronty, latenci a zastaralý obsah.