---
title: "05 REST-API"
description: "## 5.1 Allgemeines Der MCDMS WebService stellt eine REST-basierte HTTPS-Schnittstelle zum Austausch von Dateien bereit. Alle Endpunkte verwenden das HTTP-Protokoll und liefern standardisierte HTTP-Statuscodes zurück. Die Schnittstelle ist plattformunabhängig und kann von jeder Programmiersprache verwendet werden, die HTTPS-Anfragen unterstützt. ##…"
url: "https://aspi-gmbh.de/docs/05-rest-api/"
updated: "2026-07-29"
category: Anleitungen / MCDMS WebService
---

# 05 REST-API

## 5.1 Allgemeines

Der MCDMS WebService stellt eine REST-basierte HTTPS-Schnittstelle zum Austausch von Dateien bereit.

Alle Endpunkte verwenden das HTTP-Protokoll und liefern standardisierte HTTP-Statuscodes zurück.

Die Schnittstelle ist plattformunabhängig und kann von jeder Programmiersprache verwendet werden, die HTTPS-Anfragen unterstützt.

## 5.2 Basis-URL

Alle API-Endpunkte beginnen mit der Basisadresse des WebService.

**Beispiel**

```
https://server.meineklinik.de:5001/api/v1
```

## 5.3 Authentifizierung

Jede Anfrage muss einen gültigen API-Key enthalten.

Der API-Key wird im HTTP-Header übertragen.

| Header | Pflicht | Beschreibung |
| --- | --- | --- |
| X-API-KEY | ✔ | API-Key zur Authentifizierung |

Fehlt dieser Header oder ist der Schlüssel ungültig, antwortet der WebService mit **HTTP 401 (Unauthorized)**.

## 5.4 Standard-Header

Je nach Endpunkt werden zusätzlich folgende Header verwendet.

| Header | Pflicht | Beschreibung |
| --- | --- | --- |
| X-API-KEY | ✔ | API-Key |
| X-IK | ✔ | IK der Einrichtung |
| X-Dateiname | abhängig vom Endpunkt | Name der Datei |

## 5.5 Übersicht der Endpunkte

| Methode | Endpunkt | Beschreibung |
| --- | --- | --- |
| POST | /api/v1/nachrichten | Datei hochladen |
| GET | /api/v1/nachrichten | Datei herunterladen |
| GET | /api/v1/nachrichten/liste | Dateiliste abrufen |
| DELETE | /api/v1/nachrichten | Datei löschen |
| GET | /api/v1/status | Statusinformationen |

# 5.6 Datei hochladen

Lädt eine Datei in das Eingangsverzeichnis der angegebenen IK.

## Request

| Eigenschaft | Wert |
| --- | --- |
| Methode | POST |
| URL | /api/v1/nachrichten |

### Header

| Header | Pflicht | Beispiel |
| --- | --- | --- |
| X-API-KEY | ✔ | 8B0A... |
| X-IK | ✔ | 260820558 |
| X-Dateiname | ✔ | Auftrag.xml |

### Body

Der Request Body enthält ausschließlich den Dateiinhalt.

## Erfolgreiche Antwort

```
HTTP/1.1 200 OK
```

## Beispiel mit curl

```
curl -X POST ^
  "https://server:5001/api/v1/nachrichten" ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  -H "X-Dateiname: Auftrag.xml" ^
  --data-binary "@Auftrag.xml"
```

## Beispiel mit PowerShell

```
Invoke-WebRequest `
    -Uri "https://server:5001/api/v1/nachrichten" `
    -Method POST `
    -Headers @{
        "X-API-KEY"="123456789"
        "X-IK"="260820558"
        "X-Dateiname"="Auftrag.xml"
    } `
    -InFile "Auftrag.xml"
```

## Beispiel VB.NET

```
Dim client As New WebClient

client.Headers.Add("X-API-KEY", apiKey)
client.Headers.Add("X-IK", "260820558")
client.Headers.Add("X-Dateiname", "Auftrag.xml")

client.UploadFile(url, "POST", "Auftrag.xml")
```

## Beispiel C#

```
using var client = new HttpClient();

client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
client.DefaultRequestHeaders.Add("X-IK", "260820558");
client.DefaultRequestHeaders.Add("X-Dateiname", "Auftrag.xml");

var bytes = await File.ReadAllBytesAsync("Auftrag.xml");

await client.PostAsync(
    url,
    new ByteArrayContent(bytes));
```

# 5.7 Datei herunterladen

Lädt eine Datei aus dem Ausgangsverzeichnis herunter.

## Request

| Eigenschaft | Wert |
| --- | --- |
| Methode | GET |
| URL | /api/v1/nachrichten |

### Header

| Header | Pflicht |
| --- | --- |
| X-API-KEY | ✔ |
| X-IK | ✔ |
| X-Dateiname | ✔ |

## curl

```
curl ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  -H "X-Dateiname: Ergebnis.xml" ^
  -o Ergebnis.xml ^
  "https://server:5001/api/v1/nachrichten"
```

## PowerShell

```
Invoke-WebRequest `
    -Uri "https://server:5001/api/v1/nachrichten" `
    -OutFile Ergebnis.xml `
    -Headers @{
        "X-API-KEY"="123456789"
        "X-IK"="260820558"
        "X-Dateiname"="Ergebnis.xml"
    }
```

## VB.NET

```
Dim client As New WebClient

client.Headers.Add("X-API-KEY", apiKey)
client.Headers.Add("X-IK", "260820558")
client.Headers.Add("X-Dateiname", "Ergebnis.xml")

client.DownloadFile(url, "Ergebnis.xml")
```

# 5.8 Dateiliste abrufen

Liefert alle verfügbaren Dateien einer IK.

## Request

| Eigenschaft | Wert |
| --- | --- |
| Methode | GET |
| URL | /api/v1/nachrichten/liste |

### curl

```
curl ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  "https://server:5001/api/v1/nachrichten/liste"
```

### Beispielantwort

```
[
  {
    "dateiname":"Auftrag.xml",
    "groesse":24581,
    "erstelltAm":"2026-07-24T08:31:44"
  },
  {
    "dateiname":"Befund.pdf",
    "groesse":482331,
    "erstelltAm":"2026-07-24T09:12:18"
  }
]
```

# 5.9 Datei löschen

Löscht eine Datei aus dem Ausgangsverzeichnis.

## Request

| Eigenschaft | Wert |
| --- | --- |
| Methode | DELETE |
| URL | /api/v1/nachrichten |

### curl

```
curl -X DELETE ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  -H "X-Dateiname: Ergebnis.xml" ^
  "https://server:5001/api/v1/nachrichten"
```

## Erfolgreiche Antwort

```
HTTP/1.1 200 OK
```

# 5.10 Status-Endpunkt

Dient zur Überwachung und Funktionsprüfung des WebService.

## Request

| Eigenschaft | Wert |
| --- | --- |
| Methode | GET |
| URL | /api/v1/status |

## curl

```
curl https://server:5001/api/v1/status
```

## Antwort

```
{
    "status":"OK",
    "version":"1.0.0",
    "serverTime":"2026-07-24T10:18:42",
    "uptime":"12.03:44:18"
}
```

# 5.11 HTTP-Statuscodes

| Code | Bedeutung | Ursache |
| --- | --- | --- |
| 200 | OK | Anfrage erfolgreich |
| 400 | Bad Request | Ungültige Header oder Parameter |
| 401 | Unauthorized | API-Key fehlt oder ist ungültig |
| 403 | Forbidden | IK nicht freigegeben |
| 404 | Not Found | Datei nicht gefunden |
| 409 | Conflict | Datei existiert bereits |
| 413 | Payload Too Large | Datei zu groß |
| 500 | Internal Server Error | Interner Fehler |

# 5.12 Typischer Kommunikationsablauf

```
Client
   │
   │ HTTPS
   ▼
API-Key prüfen
   │
   ▼
IK prüfen
   │
   ▼
Datei speichern
   │
   ▼
Meta-Datei erzeugen
   │
   ▼
HTTP 200 OK
```

# 5.13 Test der REST-API

Nach der Installation empfiehlt sich folgender Funktionstest:

| Schritt | Erwartetes Ergebnis |
| --- | --- |
| Status-Endpunkt aufrufen | HTTP 200 |
| Testdatei hochladen | Datei im Eingangsordner vorhanden |
| Dateiliste abrufen | Testdatei wird angezeigt |
| Datei herunterladen | Inhalt identisch mit Original |
| Datei löschen | Datei wurde entfernt |

Damit ist sichergestellt, dass

- der Windows-Dienst läuft,
- die HTTPS-Kommunikation funktioniert,
- der API-Key korrekt konfiguriert wurde,
- die IK freigegeben ist,
- die Dateiverzeichnisse erreichbar sind,
- Schreib- und Leseberechtigungen korrekt gesetzt wurden.