Request- und Response-Konventionen

Basis-URL und HTTPS

Alle öffentlichen Anfragen verwenden HTTPS und beziehen sich auf folgende Basis-URL:

https://api.jobhandy.io/v1

Das Segment v1 ist Bestandteil des öffentlichen Versionsvertrags.

Standard-Request-Header

Header	Erforderlich	Zweck
`X-API-Key`	Bei geschützten Endpoints	Server-zu-Server-Authentifizierung
`X-Tenant-ID`	Bedingt	Schränkt den Tenant-Kontext ein oder löst ihn auf, wo dies dokumentiert ist
`X-Request-ID`	Nein, empfohlen	Korreliert einen einzelnen HTTP-Request-Versuch
`Content-Type: application/json`	Bei JSON-Schreibvorgängen	Deklariert den Medientyp des Request-Bodys
`Accept: application/json`	Optional bei JSON	Fordert eine JSON-Repräsentation an

Unbekannte oder nicht unterstützte Header können mit UNSUPPORTED_HEADER abgelehnt werden.

Verhalten von JSON-Requests

Senden Sie UTF-8-codiertes JSON.
Request-Schemas sind geschlossen; unbekannte Eigenschaften werden abgelehnt.
PATCH-Bodies müssen mindestens eine dokumentierte Eigenschaft enthalten.
Ausgelassene Patch-Eigenschaften bleiben unverändert.
Eine nullable Patch-Eigenschaft kann mit JSON null geleert werden.
Ein leerer String ist ein String-Wert und nicht gleichbedeutend mit null oder einer ausgelassenen Eigenschaft.
Enum-Werte sind case-sensitive.
Dokumentierte JSON-Request-Bodies besitzen eine maximale Request-Größe von 5 MiB.

{
  "phoneNumber": null
}

Dies löscht eine nullable Telefonnummer. Wird phoneNumber weggelassen, bleibt der bestehende Wert unverändert.

Verhalten von JSON-Responses

Erfolgreiche Ressourcen-Responses verwenden das von der jeweiligen Operation dokumentierte Schema. Collection-Responses enthalten Elemente und Seitenmetadaten entsprechend dem ressourcenspezifischen Page-Schema. Clients müssen unbekannte Response-Eigenschaften tolerieren, da additive Felder ohne Änderung des Pfads /v1 eingeführt werden können.

Fehler-Envelope

Jeder öffentliche API-Fehler verwendet dieselbe Top-Level-Struktur:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The supplied API key is missing, invalid, or inactive.",
    "requestId": "018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4"
  }
}

Verwenden Sie error.code für Programmverzweigungen, error.message für die Diagnose und error.requestId für die Korrelation.

Binäre Responses

Download-Endpoints für Anhänge und Payroll-Dokumente geben Binär- oder Textinhalte zurück, nicht eine JSON-Ressource.

Behandeln Sie die Dokument-ID als undurchsichtigen Identifikator.
Verwenden Sie den Response-Header Content-Type, statt den Dateityp aus dem Endpoint abzuleiten.
Verwenden Sie den Response-Dateinamen, sofern die Operation einen entsprechenden Header liefert.
Interpretieren Sie einen Fehler-Body nicht als Datei; prüfen Sie zuerst HTTP-Status und Medientyp.
Schützen Sie heruntergeladene Dateien, nachdem sie die API-Grenze verlassen haben.

Request-Größenlimits

Request-Typ	Limit des öffentlichen Vertrags
Dokumentierter JSON-Write-Body	5 MiB
Vollständiger Incident-Multipart-Body	5 MiB
Anzahl Incident-Dateien	1 bis 5 Dateien

Das Multipart-Limit gilt für den vollständigen codierten Body, nicht nur für die Summe der ursprünglichen Dateigrößen.

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

Request- und Response-Konventionen

Basis-URL und HTTPS

Standard-Request-Header

Verhalten von JSON-Requests

Verhalten von JSON-Responses

Fehler-Envelope

Binäre Responses

Request-Größenlimits

​Basis-URL und HTTPS

​Standard-Request-Header

​Verhalten von JSON-Requests

​Verhalten von JSON-Responses

​Fehler-Envelope

​Binäre Responses

​Request-Größenlimits

Basis-URL und HTTPS

Standard-Request-Header

Verhalten von JSON-Requests

Verhalten von JSON-Responses

Fehler-Envelope

Binäre Responses

Request-Größenlimits