Pojasnite zadatak i odluku
Ovaj vodič pretvara api quickstart u radni tijek koji se može pregledati. Povezuje odluke o domeni, vlasništvo, dokaze i prihvaćanje tako da rezultat nastavlja raditi u proizvodnji.
Započnite s jednim provjerenim zahtjevom, potvrdite ugovor o odgovoru i dodajte obradu kvarova prije povezivanja CMS.
Praktični postupak
- 1
Vrste izvora inventara, identifikatori, polja, lokalizacije, vlasnici i stanja publikacije.
- 2
Odaberite uzorak isporuke između volumena, latencije, uredničke kontrole i tolerancije kvarova.
- 3
Mapirajte izvorni zapis u zasebni zapis jezične verzije s trajnom vezom.
- 4
Dodajte autentifikaciju, idempotenciju, ponovni pokušaj, poništavanje predmemorije, bilježenje i kontrole pristupa.
- 5
Probno objavljivanje, promjene izvora, nedostupni rezultati, vraćanje, rad tipkovnice i praćenje prije izdavanja.
Primjer ili alat
Potpuni par zahtjeva i odgovora uključuje provjeru autentičnosti, lokalizaciju, način rada, idempotenciju i rukovanje pogreškama. U alat također zabilježite početnu vrijednost, vlasnika, odluku, dokaze, otvoreni problem i datum odobrenja. Koristite pravu stranicu ili transakciju kako bi tim vidio ovisnosti, iznimke i rad na održavanju koji slijedi nakon izdavanja.
| Točka odluke | Snimiti | Kriterij prihvatljivosti |
|---|---|---|
| Osnovna linija | Promatrano trenutno stanje | Izvor i datum snimanja |
| Odluka | Odabrana opcija i obrazloženje | Rizik i publika uzeti u obzir |
| Dokaz | Testirajte, dokumentirajte ili izmjerite | Može se pregledati i ovisi o verziji |
| Odobrenje | Ime, uloga i datum | Zadovoljeni svi obvezni kriteriji |
Pošaljite jedan zahtjev u obliku proizvodnje
Stvorite integracijski klijent na strani poslužitelja i pohranite njegove vjerodajnice u tajnom upravitelju postavljanja. Pošaljite UTF-8 JSON preko HTTPS-a sa stabilnim izvornim identifikatorom, izvornom revizijom, traženom lokacijom, načinom jezika i tijelom sadržaja. Dodajte ključ idempotencije koji ostaje isti kada se ponovi identičan posao. Ne izlažite vjerodajnice u kodu preglednika, datotekama repozitorija, CMS poljima, snimkama zaslona ili klijentovim vidljivim odgovorima na pogreške.
Započnite s reprezentativnom, ali neosjetljivom stranicom usluge. Uključite naslove, popise, poveznice i zakonske ili operativne uvjete tako da odgovor ostvaruje stvarni ugovor o sadržaju. Odbijte prazan izvorni identifikator, nepodržani lokalitet, nepoznat način, preveliko tijelo ili neispravnu strukturu prije pozivanja API. Postavite izričito vremensko ograničenje veze i odgovora i propagirajte identifikator korelacije u zapisnike vaše aplikacije.
| Polje zahtjeva | Svrha | Validacija |
|---|---|---|
| sourceId | Trajna veza sa zapisom CMS | Potreban, stabilan, neosoban |
| izvorna revizija | Otkriva ustajale rezultate | Obavezno i nepromjenjivo za zahtjev |
| mjesto i način rada | Odabire jezična pravila | Mora biti omogućena kombinacija |
| idempotencijaKljuč | Čini ponovne pokušaje sigurnima | Ista operacija koristi isti ključ |
Potvrdite potpuni ugovor o odgovoru
Tretirajte uspješan HTTP status samo kao prvu provjeru. Potvrdite shemu odgovora, identifikator rezultata, identifikator izvora i reviziju, lokalizaciju, način jezika, status obrade, blokove sadržaja, upozorenja i verziju modela ili skupa pravila ako je isporučeno. Nepoznate enum vrijednosti i obavezna polja koja nedostaju ne bi se trebala zatvoriti u pogrešku integracije koja se može pregledati. Sačuvajte upozorenja pored nacrta jer mogu identificirati terminologiju, kvalitetu izvora ili zahtjeve za ručnim pregledom.
Pohranite generirani izlaz kao zasebnu skicu revizije umjesto prepisivanja odobrenog izvora. Snimite identifikatore zahtjeva i rezultata, postavke transformacije, vremenske oznake i hash integriteta izvorne revizije. Renderirajte razliku za recenzente i izbjegnite sav izlaz prema odredištu. Generirano označavanje nepouzdani je unos dok se ne dovrše provjera valjanosti sheme, dezinfekcija, provjere pristupačnosti i ljudsko odobrenje.
- 1
Provjerite izlazni korisni teret prema lokalnoj shemi.
- 2
Pošaljite zahtjev sa zaglavljima provjere autentičnosti, vremenskog ograničenja, idempotencije i korelacije.
- 3
Provjerite status, zaglavlja i tijelo odgovora u odnosu na prikvačeni ugovor.
- 4
Napravite zaseban CMS nacrt povezan s točnom izvornom revizijom.
- 5
Usmjerite upozorenja i razlike u ispravan red čekanja za urednički pregled.
Riješite pogreške bez dupliciranja ili gubitka rada
Istek vremena za ponovni pokušaj, kvarovi veze i ograničenja brzine samo kada je operacija idempotentna. Koristite ograničeni eksponencijalni backoff s podrhtavanjem i poštujte odgodu ponovnog pokušaja koju daje poslužitelj. Ne pokušavajte ponovno neuspjele provjere valjanosti, neuspjele provjere autentičnosti ili nepodržane opcije dok se konfiguracija ne promijeni. Stavite iscrpljene operacije u red čekanja za mrtve poruke s izvornom referencom, sigurnom kategorijom pogreške, brojem pokušaja i sljedećim odgovornim timom.
Odvojite stanje okrenuto korisniku od dijagnostičkih detalja. Urednici trebaju jasna stanja kao što su u redu čekanja, obrada, skica spremna, potrebna radnja i neuspjelo sa sigurnim sljedećim korakom. Operacijama su potrebni identifikatori zahtjeva, trajanje, kategorija statusa i povijest ponovnih pokušaja, ali ne i puni izvorni tekst u običnim zapisnicima. Upozorenje na stalnu stopu pogrešaka, rastuću starost čekanja, neuspjehe provjere autentičnosti, nepodudaranja shema i skice čija se revizija izvora promijenila tijekom obrade.
Svaka operacija koja se može ponoviti ima stabilan ključ idempotencije.
Odustajanje je ograničeno i poštuje upute o ograničenju brzine.
Dnevnici isključuju vjerodajnice i tijela nepotrebnog sadržaja.
Stavke mrtvog pisma imaju vlasnika i proceduru ponavljanja.
Zastarjeli rezultat ne može tiho zamijeniti noviju izvornu reviziju.
Dokažite integraciju prije izdavanja
Testirajte valjane zahtjeve, svaku dokumentiranu pogrešku provjere valjanosti, istekle i opozvane vjerodajnice, isteke vremena, ograničenja stope, dvostruko podnošenje, dovršavanje izvan redoslijeda, evoluciju sheme, sanaciju i promjene izvora tijekom obrade. Potvrdite da nadzor identificira svaki kvar i da obučeni operater može ponovno reproducirati ili zatvoriti stavku bez uređivanja baze podataka. Pokrenite pregled pristupačnosti i urednički pregled generirane skice umjesto samo sirovog odgovora.
Izdanje s ograničenom vjerodajnicom, definiranom stopom i ograničenjima potrošnje, nadzornim pločama, upozorenjem o vlasništvu i prekidačem za vraćanje koji zaustavlja novu generaciju bez utjecaja na objavljeni sadržaj. Prikvačite podržanu verziju ugovora i zakažite pregled nadogradnje. Zapis o prihvaćanju proizvodnje trebao bi uključivati dokaze testiranja, sigurnosno odobrenje, dokumentaciju o protoku podataka, odjavu recenzenta, upute za rad i uspješnu obnovu jednog namjerno neuspješnog posla.
Uloge, dokazi i odobrenje
Generiranje odvojite od objavljivanja. Uspješan odgovor je nacrt, a ne odobrenje. Pohranite izvorni identifikator i verziju, postavke transformacije, identifikator rezultata, stanje pregleda, odobravatelja i vrijeme objave. Kada se izvor promijeni, označite jezičnu verziju za pregled umjesto tihe zamjene odobrenog sadržaja. To omogućuje vraćanje i reviziju na više platformi.
Operacije i održavanje
Rad ne završava objavljivanjem. Povežite jezičnu verziju ili konfiguraciju s izvorom, nadzirite mjere kvalitete i usluge i definirajte konkretne okidače pregleda. Okidači uključuju promjene izvora, pravne promjene, nove potrebe publike, pitanja podrške koja se ponavljaju, tehničke promjene i incidente. Imenovani vlasnik procjenjuje okidač, otvara novu reviziju po potrebi i bilježi obnovljeno odobrenje.
Kontrolni popis za objavu
Integracija koristi trajne identifikatore izvora.
Vjerodajnice se pohranjuju na strani poslužitelja i rotiraju.
Definirano je vremensko ograničenje, ponovni pokušaj i ponašanje ograničenja brzine.
Ponovljeni zahtjevi su idempotentni.
Generirani sadržaj ulazi u stanje pregleda.
Promjene izvora poništavaju ili ponovno otvaraju verziju.
Jezična navigacija radi pomoću tipkovnice i pomoćne tehnologije.
Praćenje pokriva kvarove, redove čekanja, latenciju i zastarjeli sadržaj.