Bewährte Praktiken für geskriptete REST-APIs
Befolgen Sie diese Richtlinien beim Entwerfen und Implementieren geskripteter REST-APIs.
Befolgen Sie REST-API-Konventionen
Verwenden Sie REST-API-Standards, um eine konsistente und benutzerfreundliche Schnittstelle für Clients bereitzustellen. REST-API-Konventionen definieren ein spezifisches Verhalten für jeden Methodentyp. Verwenden Sie die folgenden Richtlinien als Ausgangspunkt für das Entwerfen Ihrer API.
- GET Abfragedaten nur für Vorgänge. Eine GET-Anforderung darf 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.
Verwenden Sie die Versionsverwaltung, um Änderungen an Ihrer API zu steuern
Verwenden Sie die Versionsverwaltung, um neue Funktionen zu implementieren und bestehende Integrationen zu vermeiden. Wenn Sie bedeutende Funktionsänderungen an Ihrer API einführen, erstellen Sie zuerst eine neue Version der API. Führen Sie kein Verhalten ein, das vorhandene Integrationen in einer veröffentlichten Version unterbricht.
Mit der Versionsverwaltung können Sie bedeutende Änderungen an Ihrer API implementieren, ohne vorhandene Clients zu beschädigen. Sie können dann die neue Version der API für neue Clients freigeben und vorhandenen Clients gleichzeitig ein Upgrade in ihrem eigenen Tempo ermöglichen.
Ermutigen Sie Clients, eine versionsspezifische API zu verwenden, oder konfigurieren Sie die API ohne Standardversion, um Clients zu zwingen, eine Version anzugeben. Sie können auch neues, optionales Verhalten verfügbar machen, indem Sie einer vorhandenen Version einen optionalen Parameter hinzufügen.
Gibt einen informativen HTTP-Statuscode zurück
Gibt einen Statuscode zurück, der die anfordernde Person über den Erfolg oder Fehler der Anforderung informiert. Gibt einen HTTP-Statuscode zurück, der dem Client hilft, das Ergebnis der Anforderung zu verstehen. Verwenden Sie die folgenden Richtlinien für allgemeine Statuscodes.
| Statuscode | Beschreibung |
|---|---|
| 200 | Gibt an, dass die Anforderung erfolgreich abgeschlossen wurde. |
| 201 | Gibt an, dass ein Datensatz erfolgreich erstellt wurde. |
| 204 | Gibt an, dass ein Datensatz erfolgreich gelöscht wurde. |
| 40X (401, 404) | Statuscodes im Bereich 400 geben einen Clientfehler an, z. B. 400 für ungültige Anforderungssyntax. |
| 50X (500, 503) | Statuscodes im Bereich 500 geben an, dass ein Serverfehler aufgetreten ist. Die Clientanforderung war möglicherweise gültig oder ungültig, aber auf dem Server ist ein Problem aufgetreten, das die Verarbeitung der Anforderung verhindert hat. |
Gibt nützliche Fehlerinformationen zurück
Stellen Sie dem Client genügend Informationen in Fehlermeldungen zur Verfügung, damit er das Problem verstehen kann, ohne in Ihrer API-Dokumentation nachschlagen zu müssen. Eine Fehlerantwort sollte eine hilfreiche Fehlermeldung sowie einen Fehlerstatuscode enthalten.
Wenn ein Client beispielsweise einen Datensatz abfragt, der nicht vorhanden ist, können Sie die Fehlermeldung „der angegebene Datensatz ist nicht vorhanden“ zurückgeben. Stellen Sie sicher, dass in der Anwendung ein Datensatz mit der ID „<id value>“ vorhanden ist.“ Zusammen mit einem 404-Statuscode.
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.
Erzwingen und testen Sie Zugriffssteuerungen
Erzwingen Sie vorhandene Zugriffssteuerungen, und benötigen Sie zusätzlichen Zugriff, um Daten zu ändern. Neben der 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 für die zugrunde liegenden Daten definierte Zugriffssteuerungen für den anfordernden Anwender angewendet werden.
Erfordert zusätzliche Zugriffssteuerungen für Vorgänge, die Daten ändern. Anforderungen wie PUT, POST und LÖSCHEN sollten eine höhere Zugriffsebene als GET erfordern. Konfigurieren Sie diese API-Ressourcen so, dass eine strengere ACL erforderlich ist.
Testen Sie Ihre Zugriffssteuerungen, sowohl Authentifizierung als auch Autorisierung, bevor Sie die API freigeben.
Erstellen Sie Tests, 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 erwartet funktioniert. Tests tragen auch dazu bei, sicherzustellen, dass Änderungen, die Sie vornehmen, das erwartete API-Verhalten nach der Veröffentlichung einer Version nicht beeinträchtigen. Sie können eine REST-Client-Anwendung verwenden, die automatisiertes Testen unterstützt, z. B. Postman, um das Testen zu erleichtern.
Tests sollten den Antwortcode, die Header und den Textinhalt entsprechend für jede von Ihnen implementierte Ressource validieren. Sie können auch Tests verwenden, um Authentifizierungsanforderungen zu validieren und zu bestätigen, dass Fehler nützliche Antworten zurückgeben.