Rest-APIs mit VBA programmieren

Wer mit VBA arbeitet, kommt heute kaum noch daran vorbei: Fast jeder interessante Online-Dienst – von Wetter- und Geo-Daten über Projektmanagement-Tools bis hin zu KI-Diensten – bietet eine Rest-API an. Dabei ist das Prinzip immer dasselbe: Du schickst eine HTTP-Anfrage an eine bestimmte URL, und der Dienst antwortet mit strukturierten Daten – in der Regel im JSON-Format. Ob Du Kundenadressen mit einem CRM abgleichen, Versandetiketten bei DHL anfordern, Aufgaben in Trello anlegen oder Texte mit DeepL übersetzen willst – hinter all diesen Integrationen steckt dieselbe Technik. VBA bringt dafür alle nötigen Werkzeuge von Haus aus mit: Ein einziger Verweis auf eine Windows-Systembibliothek genügt, um HTTP-Anfragen abzusetzen und die Antworten auszuwerten. Dieser Artikel erklärt, was eine Rest-API überhaupt ist, welche Grundbegriffe Du kennen musst, um jede beliebige API-Dokumentation selbstständig zu lesen, und wie Du eine wiederverwendbare Funktion baust, die Du als solide Basis für jeden weiteren API-Aufruf einsetzen kannst.

Was ist eine Rest-API?

REST steht für Representational State Transfer und bezeichnet einen Architekturstil für verteilte Systeme, der auf dem HTTP-Protokoll basiert. Eine Rest-API (Application Programming Interface) stellt Ressourcen – zum Beispiel Kundendatensätze, Wetterdaten oder Projektaufgaben – über eindeutige URLs bereit. Der Zugriff darauf erfolgt mit den bekannten HTTP-Methoden:

• GET: Liest eine Ressource, ohne sie zu verändern.
• POST: Legt eine neue Ressource an.
• PUT: Ersetzt eine vorhandene Ressource vollständig.
• PATCH: Aktualisiert einzelne Felder einer Ressource.
• DELETE: Löscht eine Ressource.

Im Unterschied zu älteren SOAP-Webservices – die einen aufwendigen XML-Umschlag benötigen – verwendet REST meist das leichtgewichtige JSON-Format für Anfragen und Antworten. Das macht Rest-APIs deutlich einfacher konsumierbar.

Aufbau einer Rest-API-URL

Jede Rest-API-URL besteht aus mehreren Teilen, die wir kennen müssen, bevor wir den ersten VBA-Aufruf absetzen. Nehmen wir als Beispiel eine fiktive Aufgaben-API:

https://api.beispiel.de/v1/aufgaben?status=offen&limit=10

Der erste Teil, https://api.beispiel.de, ist die Basis-URL des Dienstes. Das Segment /v1/ bezeichnet die API-Version – viele Anbieter versionieren ihre API, damit bestehender Code nicht bricht, wenn neue Funktionen hinzukommen. Der Pfad /aufgaben benennt die Ressource. Ab dem Fragezeichen folgen optionale URL-Parameter (auch “Query-String” genannt), die mit dem &-Zeichen voneinander getrennt werden.

Manche APIs ergänzen die URL um eine Ressourcen-ID, wenn ein einzelner Datensatz angesprochen wird:

https://api.beispiel.de/v1/aufgaben/42

Das Prinzip ist immer gleich – und genau das macht Rest-APIs so gut erlernbar.

HTTP-Header

Neben der URL trägt jede HTTP-Anfrage einen Satz von Headern, also Name-Wert-Paaren, die Metainformationen über den Aufruf übermitteln. Die häufigsten Header, die wir in VBA selbst setzen, sind:

• Content-Type: Gibt an, in welchem Format wir Daten senden – in der Regel application/json.
• Accept: Teilt dem Server mit, welches Antwortformat wir erwarten – ebenfalls meist application/json.
• Authorization: Enthält das Authentifizierungs-Token oder den API-Key, mit dem wir uns beim Dienst ausweisen.

Wie genau das Authentifizierungs-Token aussieht und wie man es beschafft, ist von Dienst zu Dienst unterschiedlich und Gegenstand eigener Artikel.

HTTP-Statuscodes

Die Antwort des Servers enthält immer einen dreistelligen Statuscode, der uns sofort sagt, ob der Aufruf erfolgreich war.

Folgende Auflistung zeigt die wichtigsten Codes im Überblick:

• 200 – OK: Der Aufruf war erfolgreich. Die Antwort enthält die angeforderten Daten.
• 201 – Created: Eine neue Ressource wurde erfolgreich angelegt (typisch bei POST).
• 204 – No Content: Der Aufruf war erfolgreich, aber der Server liefert keinen Antwortbody (typisch bei DELETE).
• 400 – Bad Request: Die Anfrage ist fehlerhaft, zum Beispiel wegen eines ungültigen JSON-Dokuments.
• 401 – Unauthorized: Die Authentifizierung ist fehlgeschlagen. Token oder API-Key fehlt oder ist abgelaufen.
• 403 – Forbidden: Der Zugriff ist verweigert. Das Token ist gültig, aber die nötigen Rechte fehlen.
• 404 – Not Found: Die angeforderte Ressource existiert unter dieser URL nicht.
• 422 – Unprocessable Entity: Die Anfrage ist syntaktisch korrekt, scheitert aber an der inhaltlichen Validierung (zum Beispiel Pflichtfeld fehlt).
• 429 – Too Many Requests: Das Anfrage-Limit (Rate Limit) des Dienstes wurde überschritten.
• 500 – Internal Server Error: Auf dem Server ist ein unerwarteter Fehler aufgetreten.
• 503 – Service Unavailable: Der Dienst ist vorübergehend nicht erreichbar, zum Beispiel wegen Wartungsarbeiten.

Die Codes lassen sich grob in Gruppen einteilen: 2xx steht generell für Erfolg, 4xx für einen Fehler auf der Client-Seite (zum Beispiel falscher API-Key oder ungültige URL) und 5xx für einen Fehler auf der Server-Seite. Der Code 401 bedeutet “nicht autorisiert” und weist meist auf ein fehlendes oder abgelaufenes Token hin. 404 kennst Du vielleicht schon vom Surfen im Web und bedeutet hier, dass die angeforderte Ressource unter dieser URL nicht existiert.

Das XMLHTTP-Objekt in VBA

VBA bringt von Haus aus kein eigenes HTTP-Objekt mit. Wir greifen stattdessen auf die Bibliothek Microsoft XML, v6.0 zurück, die Windows standardmäßig mitliefert. Diese enthält das Objekt MSXML2.XMLHTTP60, das uns alle nötigen Methoden und Eigenschaften für HTTP-Aufrufe bereitstellt.

Alternativ steht MSXML2.ServerXMLHTTP60 zur Verfügung. Der Unterschied: XMLHTTP60 nutzt die Proxy-Einstellungen des angemeldeten Windows-Benutzers, während ServerXMLHTTP60 eine eigene Verbindung ohne Benutzerkontext aufbaut und sich deshalb besser für serverseitige Szenarien oder Situationen eignet, in denen kein Benutzerprofil vorliegt.

Für typische Aufgaben am Entwickler-PC sind beide gleichwertig. In diesem Artikel verwenden wir XMLHTTP60.

Verweis hinzufügen

Damit wir das Objekt mit früher Bindung, also mit voller IntelliSense-Unterstützung, nutzen können, müssen wir dem VBA-Projekt einen Verweis auf die XML-Bibliothek hinzufügen.

Dazu öffnen wir im VBA-Editor den Dialog über den Befehl Extras|Verweise und aktivieren den Eintrag Microsoft XML, v6.0 (siehe Bild 1).

Bild 1: Den Verweis auf Microsoft XML, v6.0 im Verweise-Dialog aktivieren

Ab sofort können wir Variablen als MSXML2.XMLHTTP60 deklarieren und profitieren von der Typprüfung beim Kompilieren.

Die Kernmethoden von XMLHTTP60

Das Objekt arbeitet nach einem festen Ablauf, den wir uns merken sollten:

• Open: Öffnet eine Verbindung und legt Methode, URL und Synchronität fest.
• setRequestHeader: Setzt einen einzelnen HTTP-Header.
• send: Versendet die Anfrage – optional mit einem Body, zum Beispiel einem JSON-Dokument.
• status: Eigenschaft, die nach dem Aufruf den HTTP-Statuscode enthält.
• responseText: Eigenschaft, die die Antwort des Servers als Text enthält.

Der dritte Parameter von Open legt fest, ob der Aufruf asynchron erfolgen soll.

Wir übergeben hier immer False, damit der Code solange wartet, bis die Antwort eingetroffen ist.

Eine wiederverwendbare HTTPRequest-Funktion

Anstatt in jedem Modul das XMLHTTP60-Objekt neu aufzubauen, lohnt es sich, eine zentrale Funktion anzulegen, die alle API-Aufrufe kapselt.

Listing 1 zeigt diese Funktion namens HTTPRequest.

Public Function HTTPRequest(strURL As String, strMethod As String, strResponse As String, Optional strData As String, _
        Optional strAuthorization As String, Optional strContentType As String = "application/json") As Integer
    Dim objHTTP As MSXML2.XMLHTTP60
    Set objHTTP = New MSXML2.XMLHTTP60
    With objHTTP
        .Open strMethod, strURL, False
        .setRequestHeader "Accept", strContentType
        .setRequestHeader "Content-Type", strContentType
        If Not Len(strAuthorization) = 0 Then
            .setRequestHeader "Authorization", strAuthorization
        End If
        .send strData
        strResponse = .responseText
        HTTPRequest = .status
    End With
End Function

Listing 1: Die Funktion HTTPRequest kapselt alle HTTP-Aufrufe an Rest-APIs.

Die Funktion nimmt folgende Parameter entgegen:

• strURL: Der vollständige Endpunkt des API-Aufrufs.
• strMethod: Die HTTP-Methode, zum Beispiel GET, POST, PUT oder DELETE.
• strResponse: Eine leere String-Variable, in die die Antwort des Servers geschrieben wird.
• strData: Optionaler Body der Anfrage, zum Beispiel ein JSON-Dokument beim Anlegen einer neuen Ressource.
• strAuthorization: Optionaler Autorisierungsheader, zum Beispiel Bearer oder ApiKey .
• strContentType: Optionaler Content-Type, Standardwert ist application/json.

Als Rückgabewert liefert die Funktion den HTTP-Statuscode als Integer. Die aufrufende Prozedur kann diesen Wert auswerten und entsprechend reagieren.

Statuscodes auswerten

Eine typische Auswertung des Statuscodes sieht wie folgt aus. Der Select Case-Block behandelt die häufigsten Fälle.

Dim intStatus As Integer
Dim strResponse As String
intStatus = HTTPRequest( _
    "https://api.beispiel.de/v1/daten", _
    "GET", strResponse)
Select Case intStatus
    Case 200, 201
        'Erfolg: Antwort verarbeiten
        Debug.Print strResponse
    Case 401
        MsgBox "Authentifizierung fehlgeschlagen." _
            & " Token prüfen."
    Case 404
        MsgBox "Endpunkt nicht gefunden."
    Case Else
        MsgBox "Fehler: " & intStatus _
            & vbCrLf & strResponse
End Select

Beachte, dass die Codes 200 und 201 beide Erfolg bedeuten: 200 steht für einen allgemeinen Erfolg, 201 für das erfolgreiche Anlegen einer neuen Ressource per POST. Viele APIs verwenden beide.

https://api.beispiel.de/v1/aufgaben?status=offen&limit=10

https://api.beispiel.de/v1/aufgaben/42

Public Function HTTPRequest(strURL As String, strMethod As String, strResponse As String, Optional strData As String, _
        Optional strAuthorization As String, Optional strContentType As String = "application/json") As Integer
    Dim objHTTP As MSXML2.XMLHTTP60
    Set objHTTP = New MSXML2.XMLHTTP60
    With objHTTP
        .Open strMethod, strURL, False
        .setRequestHeader "Accept", strContentType
        .setRequestHeader "Content-Type", strContentType
        If Not Len(strAuthorization) = 0 Then
            .setRequestHeader "Authorization", strAuthorization
        End If
        .send strData
        strResponse = .responseText
        HTTPRequest = .status
    End With
End Function

Dim intStatus As Integer
Dim strResponse As String
intStatus = HTTPRequest( _
    "https://api.beispiel.de/v1/daten", _
    "GET", strResponse)
Select Case intStatus
    Case 200, 201
        'Erfolg: Antwort verarbeiten
        Debug.Print strResponse
    Case 401
        MsgBox "Authentifizierung fehlgeschlagen." _
            & " Token prüfen."
    Case 404
        MsgBox "Endpunkt nicht gefunden."
    Case Else
        MsgBox "Fehler: " & intStatus _
            & vbCrLf & strResponse
End Select

Oder hast Du eine konkrete Frage zu Deiner eigenen Access-Anwendung?

Vielleicht stellt Deine Anwendung Dich vor eine Herausforderung, zu der Du bisher keine Lösung findest. Schlechte Performance, kein ausreichender Zugriffsschutz, Du bist unsicher über Dein Datenmodell oder Dein Code liefert unerklärliche Fehler?

In unserem kostenlosen Access-Audit schaut sich André Minhorst persönlich gemeinsam mit Dir Deine Lösung per Zoom an – und zeigt Dir, wo Datenmodell, VBA-Code, Ergonomie und Sicherheit Optimierungspotenzial bieten.