This website uses Cookies to provide you with the best possible service. Please see our Privacy Policy for more information. Click the check box below to accept cookies. Then confirm with a click on "Save".  

OpenAPI

Einführung ⬆️

Wir bieten unsere API auf Basis des OpenAPI Standards im REST-Stil an.

Der öffentliche Endpunkt für die API in dieser Version ist: /v2.2/

Alle Anfragen an unsere API dieser Version müssen an diese URL gestellt werden.

Die OpenAPI Spezifikation dieser API stellen wir als yaml Datei zur Verfügung: /v2.2/api/openapi.yaml

API Schnittstellen-Beschreibung ⬆️

Wir stellen hierzu eine OpenAPI GUI zur Verfügung in der alle Pfade und Schemata aufgeführt und detailliert erklärt sind.

Handhabung

Header-Daten ⬆️

Neben den eigentlichen Anfragedaten im Body, müssen bei jeder Anfrage noch folgende Header Informationen mitgesendet werden:

API_Angabe_Daten_im_Header

Response-Daten ⬆️

Grundsätzlich wird als Antwort immer ein JSON encoded String zurückgeliefert, der je nach Route/Anfrage und HTTP-Statuscode unterschiedlich ausgeprägt sein kann.
Lediglich im Ausnahmefall HTTP-Statuscode = 5xx (server errors) wird ein reiner Fehlerstring zurückgeliefert.
Die Response-Daten bei erfolgreichen Anfragen (HTTP-Statuscode = 200) finden Sie in der Beschreibung der entsprechenden Route.

Beispiel Response; HTTP-Statuscode = 400; ungültige Anfrage

{
  "bSuccess": false,
  "aMessage": [
    {
      "sKey": "error",
      "sValue": "CDM: Access denied (code BQW124)"
    },
    {
      "sKey": "logId",
      "sValue": "2024042414550166290125d0fc8"
    }
  ],
  "sData": ""
}
  • bSuccess hat den Wert false
  • aMessage enthält ein Array mit Erläuterungen zu Fehlern
    • sKey => level "error"
    • sValue => message
  • Data ist in dem Fall nicht gesetzt (keine konkreten Daten verfügbar)

validate Option - Prüfen der Anfrage gegen API Spezifikation ⬆️

Wir bieten die Möglichkeit die Anfrage die an unsere API gestellt wird, hinsichtlich Aufbau gegen unsere API Spezifikation prüfen zu lassen bevor sie eingespielt werden.

Das kann dazu genutzt werden die Anfragen an unsere API fehlerfrei zu programmieren.

Dazu muss lediglich im Header der Anfrage der Schalter validate:1 mitgegeben werden.

Wird der Header mitgegeben, so prüft die API, ob die übergebene Anfrage der entsprechenden OpenAPI Spezifikation entspricht und gibt einen Bericht (JSON) zurück.

curl Anfrage mit validate Option 

curl -X 'PUT' 'https://test.api.mediafinanz.de/v2.2/collect/claim/new/' \
-H'accept: application/json' \
-H'Content-Type: application/json' \
-H'uuid:..' \
-H'user:..' \
-H'password:..' \
-d'{...}' \
-H'validate:1'

✅ Response; Anfrage war fehlerfrei 

{
  "bSuccess": true,
  "aMessage": [],
  "aValidationResult": []
}

🚫 Response; Anfrage weist Fehler auf

{
  "bSuccess": false,
  "aMessage": [],
  "aValidationResult": [
    {
      "name": "ClientNo",
      "code": "error_type",
      "value": "75362",
      "in": "body",
      "expected": "integer",
      "used": "string"
    }
  ]
}
  • Hier wird bemängelt, dass im Feld "ClientNo" ein Fehler vorliegt
  • Erwartet wurde der Wert "75362" als integer
  • Übergeben wurde der Wert jedoch als string

Links ⬆️