Bewährte Methoden für Scripted REST APIs

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 3 Minuten Lesedauer

    • Befolgen Sie diese Richtlinien beim Entwerfen und Implementieren geskripteter REST APIs.

    REST-API-Konventionen befolgen

    Verwenden Sie REST-API-Standards, um eine konsistente und benutzerfreundliche Oberfläche für Clients bereitzustellen. REST-API-Konventionen definieren ein bestimmtes Verhalten für jeden Methodentyp. Verwenden Sie die folgenden Richtlinien als Ausgangspunkt für das Design Ihrer API.

    • GET Nur Vorgänge fragen Daten ab. Eine GET-Anfrage sollte niemals Daten ändern.
    • POST Vorgänge erstellen neue Datensätze, ändern jedoch keine vorhandenen Datensätze.
    • PUTUnd PATCHVorgänge ändern vorhandene Datensätze.
    • DELETE Vorgänge zerstören Datensätze.

    Versionsverwaltung verwenden, um Änderungen an Ihrer API zu steuern

    Verwenden Sie die Versionsverwaltung, um neue Funktionen zu implementieren, und um zu vermeiden, vorhandene Integrationen zu zerstören. Wenn Sie wesentliche Änderungen an der Funktionalität Ihrer API vornehmen, erstellen Sie zuerst eine neue Version der API. Führen Sie kein Verhalten ein, das vorhandene Integrationen in einer veröffentlichten Version zerstört.

    Durch die Versionsverwaltung können Sie erhebliche Änderungen an Ihrer API vornehmen, ohne vorhandene Clients zu zerstören. Sie können dann die neue Version der API für neue Clients freigeben, während vorhandene Clients in ihrem eigenen Tempo aktualisiert werden können.

    Bitten Sie Clients, eine versionsspezifische API zu verwenden, oder konfigurieren Sie die API ohne eine Standardversion, damit Clients eine Version angeben müssen. Sie können auch neues, optionales Verhalten zur Verfügung stellen, indem Sie einer vorhandenen Version einen optionalen Parameter hinzufügen.

    Informative HTTP-Statuscodes zurückgeben

    Geben Sie einen Statuscode zurück, der die anfordernde Person über eine erfolgreiche oder fehlgeschlagene Anforderung informiert. Geben Sie einen HTTP-Statuscode zurück, der dem Client hilft, das Ergebnis der Anforderung zu verstehen. Verwenden Sie die folgenden Richtlinien für allgemeine Statuscodes.

    Tabelle : 1. Allgemeine Statuscodes
    Statuscode Beschreibung
    200 Zeigt an, dass die Anforderung erfolgreich abgeschlossen wurde.
    201 Zeigt an, dass ein Datensatz erfolgreich erstellt wurde.
    204 Zeigt an, dass ein Datensatz erfolgreich gelöscht wurde.
    40X (401, 404) Statuscodes im Bereich 400 zeigen einen Client-Fehler an, z. B. 400 für ungültige Anforderungssyntax.
    50X (500, 503) Statuscodes im Bereich von 500 zeigen an, dass ein Serverfehler aufgetreten ist. Die Clientanforderung war gültig oder ungültig, aber auf dem Server ist ein Problem aufgetreten, das die Verarbeitung der Anforderung verhindert hat.

    Nützliche Fehlerinformationen zurückgeben

    Stellen Sie dem Client genügend Informationen in Fehlermeldungen zur Verfügung, damit er das Problem verstehen kann, ohne auf Ihre API-Dokumentation zugreifen zu müssen. Eine Fehlerantwort sollte eine hilfreiche Fehlermeldung sowie einen Fehlerstatuscode enthalten.

    Wenn ein Client beispielsweise einen nicht vorhandenen Datensatz abfragt, können Sie die Fehlermeldung „Der angegebene Datensatz ist nicht vorhanden. Stellen Sie sicher, dass ein Datensatz mit der ID <id value> in der Anwendung vorhanden ist.“ sowie einen Statuscode 404 zurückgeben.

    Die geskriptete REST-API-Funktion enthält mehrere vorkonfigurierte Fehlerobjekte, die Sie für häufig auftretende Fehler verwenden können, und ein anpassbares ServiceRequest-Fehlerobjekt, das Sie verwenden können, wenn die vorkonfigurierten Fehlerobjekte nicht Ihren Anforderungen entsprechen.

    Zugriffskontrollen erzwingen und testen

    Erzwingen Sie vorhandene Zugriffskontrollen, und fordern Sie zusätzlichen Zugriff an, um Daten zu ändern. Zusätzlich zur Authentifizierung für den Zugriff auf die API ist eine Autorisierung für den Zugriff auf Daten erforderlich. Verwenden Sie GlideRecordSecure API in Ihren geskripteten REST API-Skripts. Diese API stellt sicher, dass Zugriffskontrollen für die zugrunde liegenden Daten für den anfordernden Benutzer angewendet werden.

    Erfordert zusätzliche Zugriffskontrollen für Vorgänge, die Daten ändern. Anforderungen wie PUT, POST und DELETE sollten eine höhere Zugriffsstufe als GET erfordern. Konfigurieren Sie diese API-Ressourcen so, dass eine strengere ACL erforderlich ist.

    Testen Sie Ihre Zugriffskontrollen (sowohl Authentifizierung als auch Autorisierung), bevor Sie die API freigeben.

    Tests erstellen, um die Funktionalität zu überprüfen

    Erstellen Sie Tests, die die Funktionalität Ihrer geskripteten REST-Webservices als Teil Ihres Entwicklungsprozesses verifizieren. Verwenden Sie wiederholbare Tests, um sicherzustellen, dass Ihre API wie vorgesehen funktioniert. Durch das Testen wird außerdem sichergestellt, dass die von Ihnen vorgenommenen Änderungen das erwartete API-Verhalten nach der Veröffentlichung einer Version nicht beeinflussen. Sie können eine REST-Client-Anwendung verwenden, die automatisierte Tests unterstützt, wie z. B. Postman, um das Testen zu erleichtern.

    Tests sollten den Antwortcode, die Kopfzeilen und den Inhalt für jede Ressource, die Sie implementieren, überprüfen. Sie können Tests auch verwenden, um die Authentifizierungsanforderungen zu überprüfen, und um zu bestätigen, dass Fehler nützliche Antworten liefern.