Clarifier la tâche et la décision
Ce guide transforme le démarrage rapide de l'API en un flux de travail opérationnel révisable. Il relie les décisions de domaine, la propriété, les preuves et l'acceptation afin que le résultat continue de fonctionner en production.
Commencez par une demande authentifiée, validez le contrat de réponse et ajoutez la gestion des échecs avant de connecter le CMS.
Méthode pratique
- 1
Types de sources d'inventaire, identifiants, champs, paramètres régionaux, propriétaires et états de publication.
- 2
Choisissez le modèle de livraison parmi le volume, la latence, le contrôle éditorial et la tolérance aux pannes.
- 3
Mappez l’enregistrement source à un enregistrement de version linguistique distincte avec un lien durable.
- 4
Ajoutez l'authentification, l'idempotence, les nouvelles tentatives, l'invalidation du cache, la journalisation et les contrôles d'accès.
- 5
Testez la publication, les modifications de source, les résultats indisponibles, la restauration, le fonctionnement du clavier et la surveillance avant la publication.
Exemple ou outil
Une paire complète de requête et de réponse comprend l'authentification, les paramètres régionaux, le mode, l'idempotence et la gestion des erreurs. Dans l'outil, enregistrez également la référence, le propriétaire, la décision, les preuves, le problème en suspens et la date d'approbation. Utilisez une page ou une transaction réelle pour que l'équipe voie les dépendances, les exceptions et le travail de maintenance qui suit la publication.
| Point de décision | Enregistrer | Critère d'acceptation |
|---|---|---|
| Référence | État actuel observé | Source et date d'enregistrement |
| Décision | Option sélectionnée et justification | Risque et public pris en compte |
| Preuve | Tester, documenter ou mesurer | Révisable et spécifique à la version |
| Approbation | Nom, rôle et date | Tous les critères obligatoires sont remplis |
Envoyer une demande en forme de production
Créez un client d'intégration côté serveur et stockez ses informations d'identification dans le gestionnaire de secrets de déploiement. Envoyez du JSON UTF-8 via HTTPS avec un identifiant source stable, la révision source, les paramètres régionaux demandés, le mode linguistique et le corps du contenu. Ajoutez une clé d'idempotence qui reste la même lorsque le travail identique est réessayé. N'exposez pas les informations d'identification dans le code du navigateur, les fichiers du référentiel, les champs CMS, les captures d'écran ou les réponses d'erreur visibles par le client.
Commencez par une page de service représentative mais non sensible. Incluez des titres, des listes, des liens et une condition juridique ou opérationnelle afin que la réponse exerce le véritable contrat de contenu. Rejetez un identifiant source vide, un paramètre régional non pris en charge, un mode inconnu, un corps surdimensionné ou une structure mal formée avant d'appeler le API. Définissez un délai d'expiration de connexion et de réponse explicite et propagez un identifiant de corrélation dans vos journaux d'application.
| Champ de demande | But | Validation |
|---|---|---|
| identifiant source | Lien durable vers l'enregistrement CMS | Obligatoire, stable, non personnel |
| sourceRévision | Détecte les résultats obsolètes | Obligatoire et immuable pour la demande |
| paramètres régionaux et mode | Sélectionne les règles de langue | Doit être une combinaison activée |
| idempotenceClé | Sécurise les tentatives | La même opération utilise la même clé |
Valider le contrat de réponse complet
Considérez un statut HTTP réussi comme une première vérification. Validez le schéma de réponse, l'identifiant de résultat, l'identifiant et la révision de la source, les paramètres régionaux, le mode de langue, l'état de traitement, les blocs de contenu, les avertissements et la version du modèle ou de l'ensemble de règles, le cas échéant. Les valeurs d'énumération inconnues et les champs obligatoires manquants devraient échouer et entraîner une erreur d'intégration révisable. Conservez les avertissements à côté du brouillon, car ils peuvent identifier la terminologie, la qualité de la source ou les exigences de révision manuelle.
Stockez la sortie générée en tant que brouillon de révision distinct plutôt que d’écraser la source approuvée. Enregistrez les identifiants de demande et de résultat, les paramètres de transformation, les horodatages et un hachage d'intégrité de la révision source. Affichez une différence pour les réviseurs et échappez à toutes les sorties en fonction de leur destination. Le balisage généré est une entrée non fiable jusqu'à ce que la validation du schéma, la désinfection, les contrôles d'accessibilité et l'approbation humaine soient terminés.
- 1
Validez la charge utile sortante par rapport à un schéma local.
- 2
Envoyez la demande avec les en-têtes d’authentification, de délai d’attente, d’idempotence et de corrélation.
- 3
Validez le statut, les en-têtes et le corps de la réponse par rapport au contrat épinglé.
- 4
Créez un brouillon CMS distinct lié à la révision source exacte.
- 5
Acheminez les avertissements et les différences vers la file d’attente de révision éditoriale appropriée.
Gérez les erreurs sans dupliquer ni perdre du travail
Réessayez les délais d'attente, les échecs de connexion et les limites de débit uniquement lorsque l'opération est idempotente. Utilisez un intervalle exponentiel plafonné avec instabilité et respectez un délai de nouvelle tentative fourni par le serveur. Ne réessayez pas les échecs de validation, les échecs d’authentification ou les options non prises en charge jusqu’à ce que la configuration soit modifiée. Placez les opérations épuisées dans une file d’attente de lettres mortes avec la référence source, la catégorie d’erreur sûre, le nombre de tentatives et la prochaine équipe responsable.
Séparez l’état destiné à l’utilisateur des détails du diagnostic. Les éditeurs ont besoin d'états clairs tels que la file d'attente, le traitement, le brouillon prêt, l'action requise et l'échec avec une prochaine étape sûre. Les opérations ont besoin des identifiants de demande, de la durée, de la catégorie de statut et de l'historique des nouvelles tentatives, mais pas du texte source complet dans les journaux ordinaires. Alerte sur le taux d'erreurs soutenu, l'âge croissant de la file d'attente, les échecs d'authentification, les incohérences de schéma et les brouillons dont la révision source a changé pendant le traitement.
Chaque opération réessayable possède une clé d’idempotence stable.
Le backoff est plafonné et respecte les instructions de limite de débit.
Les journaux excluent les informations d'identification et les corps de contenu inutiles.
Les éléments morts ont un propriétaire et une procédure de relecture.
Un résultat obsolète ne peut pas remplacer silencieusement une révision source plus récente.
Prouver l'intégration avant la sortie
Testez les demandes valides, chaque erreur de validation documentée, les informations d'identification expirées et révoquées, les délais d'attente, les limites de débit, les soumissions en double, les achèvements dans le désordre, l'évolution du schéma, la désinfection et les modifications de source pendant le traitement. Confirmez que la surveillance identifie chaque échec et qu'un opérateur formé peut relire ou fermer l'élément sans modifier la base de données. Exécutez l’accessibilité et la révision éditoriale sur le brouillon rendu plutôt que uniquement sur la réponse brute.
Lancez-le avec des informations d'identification restreintes, des limites de débit et de dépenses définies, des tableaux de bord, la propriété des alertes et un commutateur de restauration qui arrête la nouvelle génération sans affecter le contenu publié. Épinglez la version du contrat prise en charge et planifiez une révision de mise à niveau. Le dossier d'acceptation de la production doit inclure les preuves de test, l'approbation de sécurité, la documentation du flux de données, l'approbation du réviseur, les instructions d'utilisation et la restauration réussie d'un travail délibérément échoué.
Rôles, preuves et approbation
Séparez la génération de la publication. Une réponse réussie est un brouillon et non une approbation. Stockez l'identifiant et la version de la source, les paramètres de transformation, l'identifiant du résultat, l'état de révision, l'approbateur et l'heure de publication. Lorsque la source change, marquez la version linguistique pour révision au lieu de remplacer silencieusement le contenu approuvé. Cela rend la restauration et l’audit possibles sur toutes les plateformes.
Opérations et entretien
Le travail ne s'arrête pas à la publication. Liez la version linguistique ou la configuration à sa source, surveillez les mesures de qualité et de service et définissez des déclencheurs de révision concrets. Les déclencheurs incluent les changements de source, les changements juridiques, les nouveaux besoins du public, les questions d'assistance récurrentes, les changements techniques et les incidents. Un propriétaire nommé évalue le déclencheur, ouvre une nouvelle révision si nécessaire et enregistre une nouvelle approbation.
Liste de contrôle avant publication
L'intégration utilise des identifiants de source durables.
Les informations d'identification sont stockées côté serveur et alternées.
Le comportement en matière de délai d'attente, de nouvelle tentative et de limite de débit est défini.
Les demandes répétées sont idempotentes.
Le contenu généré entre dans un état de révision.
Les modifications de source invalident ou rouvrent la version.
La navigation linguistique fonctionne par clavier et technologie d'assistance.
La surveillance couvre les échecs, les files d'attente, la latence et le contenu obsolète.