Nachdem Sie Ihre API-Dokumentation erstellt und zur Veröffentlichung vorbereitet haben, stellt sich eine zentrale Frage: Wer sollte sie einsehen können?
Soll die Dokumentation komplett öffentlich sein? Oder auf Ihr internes Team beschränkt? Vielleicht benötigen Ihre externen Partner Zugriff – aber nicht jeder.
Für jedes Szenario eine separate Version der Dokumentation zu erstellen, wäre zeitaufwändig und ineffizient. In Wirklichkeit sind die Zugriffsbedürfnisse oft sehr spezifisch – vielleicht sollte nur eine bestimmte Abteilung sie sehen, oder Ihre Partner sollten nur aus ihrem Unternehmensnetzwerk darauf zugreifen können.
Glücklicherweise bietet Apidog mehrere Optionen zur Zugriffskontrolle, um all diese Anforderungen zu erfüllen. Wählen Sie beim Veröffentlichen einer Dokumentationsseite einfach die Zugriffskontrollmethode, die zu Ihrem Anwendungsfall passt.
1. Öffentlich: Jeder kann sie einsehen
Wenn Ihre API für die öffentliche Nutzung offen ist – wie die Open API Ihres Produkts – stellen Sie die Zugriffskontrolle einfach auf "Öffentlich". Jeder mit dem Link kann die Dokumentation einsehen.
Profi-Tipp: Apidog bietet auch einen API Hub, eine Marktplatz-ähnliche Plattform, auf der Entwickler APIs durchsuchen und entdecken können. Veröffentlichen Sie Ihre Dokumentation dort, um Sichtbarkeit und Akzeptanz zu erhöhen.
2. Passwortgeschützt: Einfache Barriere
Manchmal möchten Sie Ihre Dokumentation nicht vollständig öffentlich machen, aber auch einen komplexen Aufbau vermeiden. Passwortschutz ist eine unkomplizierte Lösung – legen Sie ein Passwort fest, und nur diejenigen, die es kennen, können auf die Dokumentation zugreifen.
Die Einrichtung ist einfach:
- Wählen Sie „Passwortgeschützt“
- Legen Sie ein Passwort manuell fest oder lassen Sie es vom System generieren
- Teilen Sie es mit Kollegen oder Partnern
Am besten geeignet für: Kurzfristige oder temporäre Freigaben, wie zum Beispiel, wenn ein Partner Ihr API-Design überprüfen soll. Danach aktualisieren Sie einfach das Passwort oder nehmen die Dokumentation offline. Einfach und sauber.
Aber beachten Sie: Passwörter können unbeabsichtigt weitergegeben werden. Wenn Sie eine strengere Kontrolle benötigen, ziehen Sie andere Optionen in Betracht.
3. IP-Zulassungsliste: Zugriff auf bestimmte Netzwerke beschränken
Wenn Ihr Team oder Ihre Partner an festen Bürostandorten ansässig sind, ist die IP-Zulassungsliste möglicherweise die beste Wahl.
Es funktioniert so:
- Nur Benutzer von den angegebenen IP-Adressen oder -Bereichen können auf die Dokumentation zugreifen
- Unautorisierte IPs werden automatisch abgelehnt
Stellen Sie es sich wie eine Firewall für Ihre Dokumentation vor.
Am besten geeignet für:
- Unternehmensumgebungen
- Einschränkung des Zugriffs auf Ihr internes Netzwerk
- Partnerzugriff nur von deren Büronetzwerk aus ermöglichen
Sie können eine einzelne IP oder einen gesamten IP-Bereich konfigurieren.
Bonus: Sie können die IP-Zulassungsliste auch für den Teamprojektzugriff in den Team-Einstellungen von Apidog aktivieren (Enterprise-Plan erforderlich). Nach der Aktivierung können nur Benutzer von zugelassenen IPs auf Ihre internen Projekte zugreifen.
4. E-Mail-Zulassungsliste: Identitätsbasierter Zugriff
Sind Sie besorgt, dass Passwörter geleakt werden könnten oder IPs sich häufig ändern? Die E-Mail-Zulassungsliste ist eine flexible, sichere Alternative.
Fügen Sie einfach die E-Mail-Adressen Ihres Teams oder Ihrer Partner zur Zulassungsliste hinzu. Benutzer können dann über einen einmaligen E-Mail-Verifizierungscode auf die Dokumentation zugreifen.
Es unterstützt auch Platzhalter – zum Beispiel erlaubt *@apidog.com allen Benutzern mit der Domain Ihres Unternehmens den Zugriff auf die Dokumentation.
Vorteile:
- Einfach zu verwalten: Benutzer nach Bedarf hinzufügen oder entfernen
- Sicherer als Passwörter: Unbefugte Benutzer können die Dokumentation nicht einsehen, selbst wenn sie den Link haben
- Ideal für verteilte Teams oder mobile Mitarbeiter
5. Benutzerdefinierte Anmeldeseite: Integration mit Ihrem eigenen Authentifizierungssystem
Wenn keine der oben genannten Methoden Ihren Anforderungen entspricht, gibt es eine fortgeschrittenere Option – die Benutzerdefinierte Anmeldeseite. Diese ermöglicht es Ihnen, Ihr eigenes Authentifizierungssystem zur Steuerung des Zugriffs zu verbinden.
So funktioniert es:
- Wenn ein Benutzer versucht, auf die Dokumentationsseite zuzugreifen, wird er auf Ihre Anmeldeseite umgeleitet.
- Nach der Authentifizierung generiert Ihr Server ein JWT-Token.
- Der Benutzer wird mit dem Token als Parameter zur Dokumentationsseite zurückgeleitet.
- Apidog überprüft das Token und gewährt Zugriff, wenn es gültig ist.
Dieser Ansatz ermöglicht es Ihnen, Berechtigungen genau nach Ihren Geschäftsanforderungen zu definieren. Obwohl er etwas Entwicklungsaufwand erfordert, ist er ideal für Unternehmen mit komplexen Zugriffskontrollanforderungen.
Weitere Details zur Implementierung einer benutzerdefinierten Anmeldeseite finden Sie in den Hilfedokumenten.
So wählen Sie die richtige Zugriffskontrollmethode
Bei so vielen Optionen fragen Sie sich vielleicht: Welche soll ich wählen?
Es hängt von Ihrem Anwendungsfall ab:
| Anwendungsfall | Empfohlene Methode |
|---|---|
| Öffentliche APIs, gewünschte Sichtbarkeit | Öffentlicher Zugriff |
| Teamarbeit oder kurzfristige externe Freigabe | Passwortschutz |
| Sichere interne oder Partnernetzwerke | IP-Whitelist |
| Zugriff nach Benutzeridentität steuern | E-Mail-Whitelist |
| Eigenes Anmeldesystem nutzen | Benutzerdefinierte Anmeldeseite |
Tipp: Sie können mehrere Methoden kombinieren. Zum Beispiel:
- Verwenden Sie eine IP-Zulassungsliste für interne Teammitglieder
- Verwenden Sie eine E-Mail-Zulassungsliste für externe Partner
- Verwenden Sie Passwortschutz für temporäre Demos
Mit Apidog können Sie mehrere Dokumentationsseiten veröffentlichen, jede mit ihrer eigenen Zugriffskontrolle und einem maßgeschneiderten Satz von API-Endpunkten. Das bedeutet, dass verschiedene Zielgruppen nur das sehen, was sie sehen müssen – nicht mehr und nicht weniger.