Definér VPN-operationen, før du sammenligner API'er

En produktside siger, at den har en API, og integrationsmødet går i stå på det andet spørgsmål. Hvilken operation, mod hvilket objekt, kaldt af hvem, og hvad tæller som succes? At svare på de fire før man sammenligner produkter fjerner normalt halvdelen af kandidaterne. Det gør også den resterende sammenligning til noget, en test kan afgøre.

Erstat påstanden om at have en API med én operation

En API er en transport, ikke en evne. Et REST-endpoint, en lokal socket og en kommandolinje-indpakning kan alle kaldes en API, og de tilbyder ikke tilsvarende operationer.

Skriv operationen som en sætning, før du åbner dokumentationen.

At starte en lokal forbindelse er en klienthandling med en bruger foran sig. At udstede en enhedsprofil er en tildelingshandling med et inventar bag sig. At spærre en brugers adgang er en administrativ handling med et revisionsspor. De tre bor normalt i forskellige komponenter, ejet af forskellige teams, med forskellige beføjelser.

Fire felter gør kontrakten testbar

Udfyld fire felter for hver operation: objektet, handlingen, kalderen og succesbetingelsen. En kontrakt med et manglende felt er et ønske.

Tabellen er hele arbejdsarket:

Succesbetingelsen er det felt, folk springer over, og det er det, der afgør, om integrationen virker. En gemt indstilling er ikke en aktiv tunnel, og en deaktiveret konto er ikke en afsluttet session.

Hvis to operationer kræver forskellige kaldere, er de to integrationer. At slå dem sammen i én servicekonto betyder normalt at give flere beføjelser, end nogen af dem har brug for.

Tilpas grænsefladen til dens faktiske lag

Den fælles styringsgrænseflade i OpenVPN taler med en daemon over TCP eller en Unix-socket. Dens kommandoer omfatter tilstandsobservationer og daemonsignaler.

Det gør den til en styringskanal for daemonen, ikke en hosted abonnements-API eller en brugertilmeldingstjeneste. At læse dens dokumentation omhyggeligt forhindrer, at du bygger mod et lag, der ikke ejer objektet.

Dokumentationen siger også, at protokollen ikke har egen kryptering. Enhver, der kan nå socketten, kan styre daemonen, så behandl den som følsom styring, ikke som et metrikfeed. Bind den til loopback eller en Unix-socket, og sæt den bag en begrænset ordning, hvis en fjern kalder har brug for den. At eksponere den mod internettet af bekvemmelighed gør en styringskanal til en hændelse.

Angiv adfærd efter kaldet

Accept er ikke det samme som fuldførelse. Daemonen kan vende tilbage, før tunnelen er oppe, så vent på den dokumenterede fuldførelses- eller fejlhændelse og knyt den til den anmodning, du sendte.

Beslut, hvad kalderen gør, hvis svaret går tabt. At gentage et opret eller en genopkobling i blinde er ikke det samme som at kontrollere, om den første anmodning allerede har virket.

Fjernelse af adgang er mindst tre forskellige handlinger: bloker fremtidig login, afslut en live session, og tilbagekald legitimationsoplysningen. Bed om dem, politikken faktisk kræver, og sig i kontrakten, hvilken der er hvilken. Kald ikke en enkelt vellykket kontooppdatering for fuld tilbagekaldelse uden bevis. Forskellen betyder noget under en hændelse, når uret kører.

Prøv kontrakten med en pilot

En lille godkendt pilot bør dække succes, afvisning, afbrydelse og genforsøg, efterfulgt af den applikationsoperation, der skal tillades eller nægtes.

For en grænseflade på daemonniveau udøver to kommandoer observation og et signal:

echo state | nc -w 2 127.0.0.1 7505
echo signal SIGTERM | nc -w 2 127.0.0.1 7505

Giv kun de beføjelser, operationen kræver. Hold hemmeligheder ude af rutinelogs, og log nok private detaljer til at sige, hvilket mål der blev påvirket, og hvordan det endte.

Skriv gendannelsesvejen ned for det tilfælde, hvor selve styrings-API'en er nede. Vælg den grænseflade, der ejer objektet og dets livscyklus; automatiseringsløfter på en produktside er ikke en erstatning.