Verduidelijk de taak en het besluit
Deze handleiding verandert de API-snelstart in een beoordeelbare operationele workflow. Het verbindt domeinbeslissingen, eigendom, bewijsmateriaal en acceptatie, zodat het resultaat blijft werken in de productie.
Begin met één geverifieerd verzoek, valideer het responscontract en voeg foutafhandeling toe voordat u de CMS aansluit.
Praktische werkwijze
- 1
Inventarisatiebrontypen, ID's, velden, landinstellingen, eigenaren en publicatiestatussen.
- 2
Kies het leveringspatroon op basis van volume, latentie, redactionele controle en fouttolerantie.
- 3
Wijs het bronrecord toe aan een afzonderlijk taalversierecord met duurzame koppeling.
- 4
Voeg authenticatie, idempotentie, opnieuw proberen, cache-invalidatie, logboekregistratie en toegangscontroles toe.
- 5
Testpublicatie, bronwijzigingen, niet-beschikbare resultaten, terugdraaien, toetsenbordbediening en monitoring vóór release.
Voorbeeld of hulpmiddel
Een compleet verzoek- en antwoordpaar omvat authenticatie, landinstelling, modus, idempotentie en foutafhandeling. Leg in de tool ook de uitgangssituatie, de eigenaar, het besluit, het bewijsmateriaal, het openstaande probleem en de goedkeuringsdatum vast. Gebruik een echte pagina of transactie zodat het team afhankelijkheden, uitzonderingen en het onderhoudswerk dat volgt op de release ziet.
| Beslissingspunt | Dossier | Acceptatiecriterium |
|---|---|---|
| Basislijn | Huidige staat waargenomen | Bron en datum vastgelegd |
| Beslissing | Geselecteerde optie en reden | Er wordt rekening gehouden met risico en publiek |
| Bewijs | Test, documenteer of meet | Reviewbaar en versiespecifiek |
| Goedkeuring | Naam, rol en datum | Er werd aan alle verplichte criteria voldaan |
Stuur één productievormig verzoek
Maak een integratieclient aan de serverzijde en sla de referenties ervan op in de implementatiegeheimmanager. Verzend UTF-8 JSON via HTTPS met een stabiele bron-ID, bronrevisie, aangevraagde landinstelling, taalmodus en inhoudstekst. Voeg een idempotentiesleutel toe die hetzelfde blijft wanneer de identieke taak opnieuw wordt geprobeerd. Geef geen inloggegevens weer in browsercode, repositorybestanden, CMS-velden, schermafbeeldingen of voor de klant zichtbare foutreacties.
Begin met een representatieve maar niet-gevoelige servicepagina. Voeg koppen, lijsten, links en een juridische of operationele voorwaarde toe, zodat het antwoord het echte inhoudscontract uitoefent. Weiger een lege bron-ID, niet-ondersteunde landinstelling, onbekende modus, te grote hoofdtekst of misvormde structuur voordat u de API aanroept. Stel een expliciete verbindings- en responstime-out in en geef een correlatie-ID door in uw toepassingslogboeken.
| Verzoekveld | Doel | Geldigmaking |
|---|---|---|
| bronId | Duurzame link naar het CMS-record | Vereist, stabiel, niet-persoonlijk |
| bronRevisie | Detecteert verouderde resultaten | Vereist en onveranderlijk voor het verzoek |
| landinstelling en modus | Selecteert taalregels | Moet een ingeschakelde combinatie zijn |
| idempotentieSleutel | Maakt nieuwe pogingen veilig | Voor dezelfde bewerking wordt dezelfde sleutel gebruikt |
Valideer het volledige responscontract
Behandel een succesvolle HTTP-status alleen als de eerste controle. Valideer het antwoordschema, de resultaat-ID, bron-ID en -revisie, landinstelling, taalmodus, verwerkingsstatus, inhoudsblokken, waarschuwingen en model- of regelsetversie, indien opgegeven. Onbekende opsommingswaarden en ontbrekende verplichte velden zouden moeten mislukken en resulteren in een controleerbare integratiefout. Bewaar waarschuwingen naast het concept, omdat ze terminologie, bronkwaliteit of vereisten voor handmatige beoordeling kunnen identificeren.
Sla de gegenereerde uitvoer op als een afzonderlijke conceptrevisie in plaats van de goedgekeurde bron te overschrijven. Registreer verzoek- en resultaat-ID's, transformatie-instellingen, tijdstempels en een integriteitshash van de bronrevisie. Geef een diff weer voor revisoren en ontsnap aan alle uitvoer op basis van de bestemming ervan. Gegenereerde markeringen zijn niet-vertrouwde invoer totdat schemavalidatie, opschoning, toegankelijkheidscontroles en menselijke goedkeuring zijn voltooid.
- 1
Valideer de uitgaande payload op basis van een lokaal schema.
- 2
Verzend het verzoek met verificatie-, time-out-, idempotentie- en correlatieheaders.
- 3
Valideer de status, headers en antwoordtekst op basis van het vastgezette contract.
- 4
Maak een afzonderlijk CMS-concept gekoppeld aan de exacte bronrevisie.
- 5
Leid waarschuwingen en diffs naar de juiste wachtrij voor redactionele beoordelingen.
Handel fouten af zonder werk te dupliceren of werk te verliezen
Time-outs, verbindingsfouten en snelheidslimieten moeten alleen opnieuw worden geprobeerd als de bewerking idempotent is. Gebruik een afgetopte exponentiële uitstel met jitter en respecteer een door de server geleverde vertraging bij nieuwe pogingen. Probeer validatiefouten, authenticatiefouten of niet-ondersteunde opties niet opnieuw totdat de configuratie is gewijzigd. Plaats uitgeputte bewerkingen in een dode-letter-wachtrij met de bronreferentie, de veilige foutcategorie, het aantal pogingen en het volgende verantwoordelijke team.
Scheid de gebruikersgerichte status van diagnostische details. Redacteuren hebben duidelijke statussen nodig, zoals in de wachtrij, verwerken, klaar voor concept, actie vereist en mislukt met een veilige volgende stap. Voor bewerkingen zijn aanvraag-ID's, duur, statuscategorie en geschiedenis van nieuwe pogingen nodig, maar niet de volledige brontekst in gewone logboeken. Waarschuwing voor aanhoudend foutenpercentage, groeiende wachtrijleeftijd, authenticatiefouten, niet-overeenkomende schema's en concepten waarvan de bronrevisie tijdens de verwerking is gewijzigd.
Elke opnieuw te proberen bewerking heeft een stabiele idempotency-sleutel.
Uitstel is beperkt en er worden de instructies voor de tarieflimiet gerespecteerd.
Logboeken sluiten inloggegevens en onnodige inhoudsteksten uit.
Dead-letter-items hebben een eigenaar en een herhalingsprocedure.
Een oud resultaat kan niet stilletjes een nieuwere bronrevisie vervangen.
Bewijs de integratie voordat deze wordt vrijgegeven
Test geldige verzoeken, elke gedocumenteerde validatiefout, verlopen en ingetrokken inloggegevens, time-outs, snelheidslimieten, dubbele indiening, voltooiing buiten gebruik, schema-evolutie, opschoning en bronwijzigingen tijdens de verwerking. Bevestig dat monitoring elke fout identificeert en dat een getrainde operator het item opnieuw kan afspelen of sluiten zonder dat de database hoeft te worden bewerkt. Voer een toegankelijkheids- en redactionele beoordeling uit op het weergegeven concept in plaats van alleen op het ruwe antwoord.
Release met een beperkte inloggegevens, gedefinieerde tarief- en bestedingslimieten, dashboards, eigendom van waarschuwingen en een terugdraaischakelaar die de nieuwe generatie stopt zonder de gepubliceerde inhoud te beïnvloeden. Zet de ondersteunde contractversie vast en plan een upgradebeoordeling. Het productieacceptatierecord moet testbewijs, veiligheidsgoedkeuring, gegevensstroomdocumentatie, aftekening door de recensent, bedieningsinstructies en het succesvol herstellen van één opzettelijk mislukte taak bevatten.
Rollen, bewijs en goedkeuring
Houd generatie gescheiden van publicatie. Een succesvol antwoord is een concept, geen goedkeuring. Bewaar de bron-ID en -versie, transformatie-instellingen, resultaat-ID, beoordelingsstatus, goedkeurder en publicatietijd. Wanneer de bron verandert, markeer dan de taalversie ter beoordeling in plaats van goedgekeurde inhoud stilzwijgend te vervangen. Dit maakt rollback en audit mogelijk op verschillende platforms.
Bediening en onderhoud
Het werk eindigt niet bij de publicatie. Koppel de taalversie of configuratie aan de bron, bewaak de kwaliteit en servicemaatregelen en definieer concrete beoordelingstriggers. Triggers zijn onder meer bronwijzigingen, juridische wijzigingen, nieuwe doelgroepbehoeften, terugkerende ondersteuningsvragen, technische wijzigingen en incidenten. Een benoemde eigenaar evalueert de trigger, opent indien nodig een nieuwe revisie en registreert de vernieuwde goedkeuring.
Controlelijst voor publicatie
De integratie maakt gebruik van duurzame bronidentificaties.
Inloggegevens worden op de server opgeslagen en gerouleerd.
Time-out, nieuwe poging en snelheidslimietgedrag zijn gedefinieerd.
Herhaalde verzoeken zijn idempotent.
Gegenereerde inhoud komt in een beoordelingsstatus.
Bronwijzigingen maken de versie ongeldig of heropenen deze.
Taalnavigatie werkt via toetsenbord en ondersteunende technologie.
Monitoring heeft betrekking op fouten, wachtrijen, latentie en verouderde inhoud.