Überblick über die CCW-API
Die REST-API von CCW ermöglicht es Kunden und Partnern, neue Anwendungen zu erstellen und auf neue Weise in CCW zu integrieren, um ihre Fähigkeiten bei der Verwaltung einer befristeten Belegschaft zu verbessern.
Mithilfe der Rest API von CCW können Kunden und Partner neue Anwendungen erstellen und sich auf neue Weise in CCW integrieren, um ihre Fähigkeiten bei der Verwaltung einer befristeten Belegschaft zu verbessern. Die APIs von CCW sind HTTP-basierte RESTful-APIs, die OAuth 2.0 für die Authentifizierung und TLS 1.2 für die Sicherheit der Transportschicht verwenden. In dieser Dokumentation wird erläutert, wie Sie auf die CCW-API zugreifen und Anfragen stellen können, um die benötigten Daten zu erhalten.
Authentifizierung
Kunden, die auf die CCW-REST-API zugreifen möchten, können ihre API-Verbraucher-App registrieren und die OAuth 2.0-Client-Anmeldeinformationen erhalten, die sie in Kombination mit zwei zusätzlichen Sicherheitsebenen - Bereiche und Benutzer-/Rollenzugriffsrechte - verwenden können, um Anfragen an die CCW-API zu authentifizieren.
| Authentifizierungsanforderung | Beschreibung |
|---|---|
| OAuth 2.0 Anmeldeinformationen | Enthält eine Kunden-ID und ein Kundengeheimnis |
| Geltungsbereiche | Die Endpunkte, die auf das spezifische Modul/die Funktionalität innerhalb von CCW verweisen, werden angefordert |
| Benutzer-/Rollenzugriffsrechte | Zugewiesen in der CCW-Anwendung. Sobald Sie von der API authentifiziert sind (siehe unten), bestimmt eine andere Sicherheitsebene den Zugriff auf die angeforderte spezifische Funktionalität |
Zugriffs-Token
Der erste Schritt beim Zugriff auf die CCW-API besteht darin, ein Zugriffstoken anzufordern, indem Sie einen Anruf mit den OAuth-Anmeldeinformationen und dem/den Geltungsbereich(en) tätigen, wie im folgenden Beispiel:
curl -XPOST -H "Inhaltstyp: application/json" -d '{"client_id": "<<clientID>>", "client_secret": "<<secret>>",
"scope":"ccw.candidate", "grant_type":"client_credential"}' 'Auth_Url'
Verwenden Sie für 'Auth_Url' je nach Umgebung Folgendes:
-
Sandbox: https://sso-stg1.coupahost.
com/as/token.oauth2 -
Produktion: https://sso-prd1.coupahost.
com/as/token.oauth2
Der Autorisierungsserver gibt eine JSON-Nutzlast zurück, die Folgendes enthält:
| Eigenschaft | Wert |
|---|---|
| token_type | Vorangestellt mit "Bearer" |
| access_token | Zeichenfolge, die beim Erstellen von API-Anfragen in den Autorisierungsheader aufgenommen werden soll |
| expires_in | Anzahl der Sekunden bis zum Ablauf des Tokens (in der Regel 3600 oder 1 Stunde) |
API-Endpunkte
Fügen Sie das Zugriffstoken ein, das in Aufrufen von CCW-API-Endpunkten empfangen wurde. Die Anfrage ist validiert (oder gibt einen Fehler zurück - siehe Fehlercodes).
Endpunktformat: https://<instance>/api/<resource path>
Beispiele:
- Kandidatenbestätigung: https://{hostname}/API/candidates/{id}/confirm
- Kandidaten-Suche: https://{hostname}/API/candidates/search
- Nachschlagen von Zeitarbeitern (CW): https://{hostname}/API/contingent_workers
Anforderungsköpfe
Folgende HTTP-Anforderungskopfzeilen sind erforderlich:
| Kopfzeile | Beschreibung |
|---|---|
| Autorisierung | Wird verwendet, um Zugriff für API-Aufrufe anzufordern. Fügen Sie das Bearer-Token dem Authentifizierungsschema hinzu: Inhaber: <Token> |
| Inhaltstyp | In allen Anfragen auf: application/json eingestellt. Json ist das einzige Austauschformat, das derzeit unterstützt wird |
| X-Korrelations-ID | Ein Bezeichner mit maximal 36 Zeichen, der generiert wird, um die Verfolgung und Überprüfung der API-Anforderung zu ermöglichen |
Fehlerantworten
Beispiel für eine Fehlerreaktion
{
"error_code": "Zeichenfolge",
"error_summary": "Zeichenfolge",
"error_causes": [
{
"error_sub_code": "Zeichenfolge",
"error_sub_code_desc": "Zeichenfolge"
}
]
}
Fehlercodes
Bitte beachten Sie die Abschnitte Fehlercodes jeder spezifischen CCW-API:
- Kandidaten-Such-API - Fehlercodes
- Kandidat bestätigt API - Fehlercodes
- CW Lookup API - Fehlercodes
Satzbegrenzung
CCW-REST-APIs haben keine explizite Ratenbegrenzung, jedoch wird die Drosselung von API-Anfragen für eine zeitnahe Antwort empfohlen. In Kürze werden die einzelnen API-Endpunkte mit der empfohlenen Ratenbegrenzung aktualisiert.
Best Practices
Im Folgenden finden Sie einige Tipps, um die besten Ergebnisse beim Erstellen von Anwendungen auf CCW mit unseren REST-APIs ZU erzielen:
- Schema-Validierung vermeiden: CCW-APIs werden ständig weiterentwickelt, wobei der API neue optionale Eigenschaften hinzugefügt werden. Aus Gründen der Erweiterbarkeit sollten Anwendungen keine Schemavalidierung durchführen, die Fehler auslösen kann, wenn die API neue Eigenschaften sendet, die möglicherweise nicht erforderlich sind.
- HTTP-Statuscodes verwenden: Verbraucheranwendungen sollten sich bei der Behandlung von API-Fehlern auf HTTP-Statuscodes verlassen und nicht auf Inhalte des Antworttextes, die nur zu Diagnose- und Protokollierungszwecken dienen.
- Vermeiden Sie je nach Reihenfolge der Eigenschaften in der API-Antwort: Die CCW-API unterstützt nur JSON-Inhalte. Die Reihenfolge der Eigenschaften in einer API-Antwort kann sich aufgrund der Einführung neuer Eigenschaften ändern.