Construire un registre de produits et de destinations avec JSON, HTTP et des versions

Champs minimaux et types fermés

Chaque produit possède un identifiant stable, un nom public, un statut éditorial, une promesse, un public et des limites. Chaque destination possède un type fermé — site, démo, application, installation, inscription ou aide — une URL HTTPS, un statut, une date de vérification et une référence de preuve. Les valeurs inconnues sont nulles ou absentes, jamais remplacées par une URL supposée.

Un schéma fermé rejette les propriétés inattendues. Il empêche qu’une donnée personnelle ou un champ interne glisse progressivement dans le snapshot public. Les dates utilisent un format non ambigu et les versions suivent une règle documentée.

• Identifiant technique stable et nom public séparés.
• Promesse et limites rédigées pour le lecteur.
• Destination typée et statut explicite.
• Date de preuve et date d’expiration éventuelle.
• Source ou passation identifiable.
• Aucun secret, jeton, compte, adresse ou contenu métier.

Exemple conceptuel

Une entrée peut déclarer qu’un guide est public, qu’une démo fictive est vérifiée et qu’une inscription est absente. Le consommateur affiche alors « Lire le guide » et « Essayer la démo », mais aucun bouton d’inscription. Si une nouvelle preuve ouvre le compte, une version ultérieure ajoute la destination sans modifier rétroactivement l’ancien snapshot.

L’exemple reste conceptuel : les noms de champs exacts dépendent du contrat versionné. L’important est que le consommateur n’interprète jamais l’absence comme une autorisation.

JSON structure, le schéma contraint

JSON fournit objets, tableaux, chaînes, nombres, booléens et null. Il ne définit pas à lui seul l’identité des champs ni leurs invariants. Un schéma ajoute types, formats, valeurs autorisées, propriétés requises et refus des champs supplémentaires. Les règles telles que « une URL d’inscription n’existe que si son statut est publiable » restent testées en plus du schéma.

L’encodage est UTF-8 et les noms officiels conservent leurs accents. Un consommateur traite une version de schéma inconnue comme indisponible ; il ne tente pas de deviner la nouvelle structure.

HTTP transporte fraîcheur et erreurs

Une réponse 200 indique qu’une représentation a été servie, pas qu’une application entière fonctionne. ETag permet au consommateur de demander si le snapshot a changé et de recevoir 304 sans le retélécharger. Cache-Control borne la fraîcheur ; un manifeste courant peut avoir une durée courte tandis qu’un snapshot adressé par empreinte peut être immuable.

Une indisponibilité renvoie un statut et un problème lisible par machine sans inclure de détail sensible. Le consommateur conserve le guide statique, masque les CTA dépendants et évite d’afficher un ancien statut comme courant au-delà de l’expiration.

Versions, migrations et compatibilité

La version de schéma change lorsque le sens ou la structure n’est plus compatible. La version de données change à chaque publication atomique. Le consommateur annonce les versions qu’il accepte et échoue fermé sur les autres. Une migration peut supporter temporairement deux versions, avec date de retrait connue et tests sur les deux.

Un renommage de produit ne change pas nécessairement l’identifiant. Le registre publie le nouveau nom et les redirections prévues, tandis que les anciennes pages cessent d’être des contenus actifs distincts.

Validation et publication atomique

Le pipeline lit la source, valide le schéma, contrôle les invariants, détecte les liens ou chemins locaux interdits, génère un snapshot candidat et demande une revue humaine des promesses. Il publie ensuite le snapshot et son manifeste comme un ensemble. En cas d’échec, la version courante reste intacte.

Le rollback réactive un snapshot antérieur identifié. Il ne reconstitue pas manuellement un mélange de champs anciens et nouveaux. Les journaux décrivent les identifiants et résultats de validation, jamais les éventuelles données privées rencontrées par erreur.

1. Lire une source versionnée.
2. Valider types, URLs et valeurs autorisées.
3. Contrôler les invariants métier de publication.
4. Scanner secrets et chemins internes.
5. Faire relire les changements de promesse.
6. Publier snapshot et manifeste atomiquement.
7. Conserver l’empreinte et le rollback.

Sécurité et minimisation

Un registre public est téléchargeable par tous : toute valeur doit donc être publiable sans authentification. Un jeton, une adresse privée, un identifiant de session ou une note interne n’y a aucune place. Les champs inutiles sont retirés plutôt que masqués côté interface, car un visiteur peut lire le JSON brut.

Les URL sont normalisées et limitées aux schémas attendus. Les redirections sont vérifiées. Une chaîne provenant d’une source externe est traitée comme donnée, jamais comme instruction de build ou de déploiement.

Checklist d’un snapshot publiable

Avant promotion, effectuez un contrôle ciblé sur le snapshot exact qui sera servi.

• Schéma et version reconnus.
• Propriétés supplémentaires refusées.
• Identifiants stables et uniques.
• URLs HTTPS exactes et destinations typées.
• Promesses reliées à une preuve datée.
• Valeurs absentes laissées absentes.
• Aucun secret, PII, chemin local ou URL de preview privée.
• ETag, cache et expiration cohérents.
• Manifeste et rollback conservés.