Définissez l'opération VPN avant de comparer les API
Le contrôle des connexions, le provisionnement des profils, l'administration des utilisateurs et l'observation sont des API différentes. Nommez d'abord l'objet, l'action et la condition de réussite.
Une page produit affirme qu'une API existe, et la réunion d'intégration bloque sur la deuxième question. Quelle opération, sur quel objet, appelée par qui, et qu'est-ce qui compte comme réussite ? Répondre à ces quatre questions avant de comparer des produits élimine généralement la moitié des candidats. Cela transforme aussi la comparaison restante en quelque chose qu'un test peut trancher.
Remplacez l'affirmation d'une API par une seule opération
Une API est un transport, pas une capacité. Un point de terminaison REST, une socket locale et un habillage en ligne de commande peuvent tous s'appeler API, et ils n'offrent pas des opérations équivalentes.
Écrivez l'opération sous forme de phrase avant d'ouvrir la documentation.
Démarrer une connexion locale est une action côté client avec un utilisateur devant. Émettre un profil d'appareil est une action de provisionnement avec un inventaire derrière. Désactiver l'accès d'un utilisateur est une action administrative avec une piste d'audit. Ces trois vivent généralement dans des composants différents, détenus par des équipes différentes, avec des autorités différentes.
Quatre champs qui rendent le contrat testable
Remplissez quatre champs pour chaque opération : l'objet, l'action, l'appelant et la condition de réussite. Un contrat auquel il manque un champ est un voeu.
Le tableau est toute la feuille de travail :
| Field | Question | Example |
|---|---|---|
| Object | What is being acted on? | One enrolled device |
| Action | Observe, create, change, start, stop, or revoke? | Revoke |
| Caller | Which identity calls it? | Deployment service |
| Success | What observable state proves it? | Future sign-in denied |
La condition de réussite est le champ que les gens sautent, et c'est elle qui décide si l'intégration fonctionne. Un réglage enregistré n'est pas un tunnel actif, et un compte désactivé n'est pas une session terminée.
Si deux opérations exigent des appelants différents, ce sont deux intégrations. Les regrouper dans un seul compte de service revient généralement à accorder plus d'autorité qu'aucune des deux n'en a besoin.
Alignez l'interface sur sa couche réelle
L'interface de gestion communautaire d'OpenVPN dialogue avec un démon via TCP ou une socket Unix. Ses commandes incluent l'observation d'état et des signaux au démon.
Cela en fait un canal de contrôle du démon, non une API d'abonnement hébergée ni un service d'enrôlement des utilisateurs. Lire sa documentation attentivement évite de construire contre une couche qui ne possède pas l'objet.
Cette documentation indique aussi que le protocole ne porte aucun chiffrement propre. Quiconque atteint la socket peut contrôler le démon, alors traitez-la comme un contrôle sensible et non comme un flux de métriques. Liez-la à loopback ou à une socket Unix, et placez-la derrière un dispositif restreint si un appelant distant en a besoin. L'exposer à internet par commodité transforme un canal de contrôle en incident.
Précisez le comportement après l'appel
L'acceptation n'est pas la même chose que l'achèvement. Le démon peut revenir avant que le tunnel soit monté, alors attendez l'événement documenté d'achèvement ou d'échec et rattachez-le à la requête envoyée.
Décidez ce que fait l'appelant si la réponse se perd. Répéter aveuglément une création ou une reconnexion n'est pas la même chose que vérifier si la première requête a déjà pris effet.
Retirer l'accès recouvre au moins trois actions différentes : bloquer la prochaine connexion, terminer une session active et révoquer le justificatif. Demandez celles que la politique exige réellement, et dites dans le contrat laquelle est laquelle. N'étiquetez pas une mise à jour de compte réussie comme une révocation complète sans preuve. La différence compte pendant un incident, quand le temps presse.
Vérifiez le contrat avec un pilote
Un petit pilote approuvé devrait couvrir la réussite, le rejet, l'interruption et la nouvelle tentative, puis l'opération applicative censée être autorisée ou refusée.
Pour une interface au niveau du démon, deux commandes exercent l'observation et un signal :
echo state | nc -w 2 127.0.0.1 7505
echo signal SIGTERM | nc -w 2 127.0.0.1 7505N'accordez que l'autorité exigée par l'opération. Gardez les secrets hors des journaux de routine et journalisez assez de détails privés pour dire quelle cible a été touchée et comment cela s'est terminé.
Écrivez le chemin de reprise pour le cas où l'API de contrôle elle-même est indisponible. Choisissez l'interface qui possède l'objet et son cycle de vie ; les promesses d'automatisation sur une page produit ne remplacent pas cela.