Eine REST-Messaging-API modelliert jeden Versand als Ressource in einer messages-Collection. Clients senden eine Nachricht per POST, und da die Zustellung asynchron ist, antwortet der Server mit 202 Accepted samt Message-Identifier und Status-URL und meldet das Endergebnis anschließend per Webhook. HTTP-Methoden und Statuscodes folgen der Semantik von RFC 9110.
- Ihre AnwendungVersand über REST API oder SMPP
- BroadNet-PlattformValidiert, routet und fakturiert jede Nachricht
- SMSC des BetreibersDirekte Operator-Anbindung
- Endgerät des AbonnentenDie Nachricht wird zugestellt
Das messages-Ressourcenmodell
Eine REST-Messaging-API behandelt jede Nachricht als Ressource unter einer Collection — konventionell /messages — adressierbar über einen serverseitig vergebenen Identifier. Die Absicht drückt das Verb aus, nicht ein Payload-Feld: POST /messages erzeugt eine neue ausgehende Nachricht und reiht sie in die Warteschlange; GET /messages/{id} liest ihren aktuellen Zustand; GET /messages listet und filtert. Dies ist die REST-Schicht über denselben Operator-Verbindungen, die SMPP auf dem Wire erreicht, sodass die vom Client per POST erzeugte Ressource downstream auf ein submit_sm einer gebundenen SMPP-Session abgebildet wird. Da der Identifier vom Server erzeugt und in der Response zurückgegeben wird (und meist in einem Location-Header gespiegelt), erhält der Client ein stabiles Handle, um zu pollen oder später mit Status-Callbacks zu korrelieren.
POST /v1/messages HTTP/1.1
Host: api.example
Content-Type: application/json
Authorization: Bearer <token>
Idempotency-Key: 8f14e45f-ea7b-4c0f-9b2a-1d2c3e4f5a6b
{
"to": "+15551234567",
"from": "BRANDNAME",
"text": "Your one-time code is 401 928",
"callback_url": "https://app.example/webhooks/dlr"
}HTTP-Methoden und ihre Garantien
RFC 9110 definiert zwei Eigenschaften, die bestimmen, wie ein Messaging-Client und jeder Intermediär eine Anfrage behandeln dürfen. Sichere Methoden (GET, HEAD) haben keine Seiteneffekte und sind frei cachebar und wiederholbar. Idempotente Methoden (GET, HEAD, PUT, DELETE) können mit demselben Nettoeffekt wiederholt werden. POST ist weder sicher noch idempotent — genau das ist das Problem beim Nachrichtenversand: ein wiederholtes POST könnte doppelt senden. Das übliche Mittel ist nicht der Missbrauch von PUT, sondern POST beizubehalten und es mit einem Idempotency-Key-Request-Header idempotent zu machen, sodass ein erneut gesendeter Versand das ursprüngliche Ergebnis zurückgibt, statt eine zweite Nachricht zu erzeugen.
| Methode | Auf /messages | Sicher | Idempotent |
|---|---|---|---|
| POST | Neue Nachricht erstellen und in die Warteschlange stellen | No | Nein (per Idempotency-Key idempotent machen) |
| GET | Eine Nachricht lesen oder die Sammlung auflisten | Ja | Ja |
| HEAD | Metadaten-/Existenzprüfung | Ja | Ja |
| PUT | Veränderbare Ressource ersetzen (z. B. eine Webhook-Konfiguration) | No | Ja |
| PATCH | Teilweise Aktualisierung einer veränderbaren Ressource | No | No |
| DELETE | Eine noch in der Warteschlange befindliche Nachricht abbrechen | No | Ja |
Statuscode-Semantik beim Senden
Der vom Server zurückgegebene Statuscode kodiert, ob die Nachricht angenommen, abgeschlossen oder abgelehnt wurde — und der Nachrichtenversand ist fast immer asynchron. RFC 9110 definiert 202 Accepted genau für diesen Fall: die Anfrage wurde zur Verarbeitung angenommen, die Verarbeitung ist jedoch nicht abgeschlossen, und die Response sollte angeben, wo der Fortschritt zu prüfen ist. Eine Messaging-API gibt daher 202 für einen eingereihten Versand zurück und reserviert 201 Created für eine vollständig materialisierte Ressource sowie 200 OK für einen wirklich synchronen Vorgang. Client-Fehler (fehlerhaftes Payload, ungültiges Ziel, unbekannter Absender) sind 4xx und dürfen nicht unverändert wiederholt werden; Server- und Upstream-Fehler sind 5xx und können mit Backoff unter demselben Idempotency-Key gefahrlos wiederholt werden.
| Code | Bedeutung | Wenn eine Messaging-API es verwendet |
|---|---|---|
| 202 Accepted | Akzeptiert, Bearbeitung unvollständig | Asynchrone Sendung in Warteschlange gestellt; endgültiger Zustand wird über einen Callback übermittelt |
| 201 Created | Ressource erstellt | Synchrone Erstellung, bei der die Ressource vollständig ist |
| 200 OK | Anfrage abgeschlossen | Synchroner Statusabruf oder wirklich sofortige Operation |
| 400 / 422 | Clientfehler / nicht verarbeitbar | Fehlerhafter Body oder ungültiges Feld – nicht unverändert wiederholen |
| 401 / 403 | Nicht authentifiziert / verboten | Fehlende oder unzureichende Zugangsdaten |
| 409 Conflict | Zustandskonflikt | Idempotency-Key mit anderer Payload wiederverwendet |
| 429 Too Many Requests | Ratenlimit überschritten | Drosseln; Retry-After beachten und Backoff anwenden |
| 5xx | Server-/Upstream-Fehler | Vorübergehend – mit Backoff unter demselben Schlüssel erneut versuchen |
Synchrone vs. asynchrone Zustellung
In einer Messaging-API gibt es zwei verschiedene Latenzen, und es ist ein Designfehler, sie zu vermischen. Die API-Latenz ist, wie lange der HTTP-Aufruf braucht, um die Nachricht anzunehmen; die Zustelllatenz ist, wie lange das Operator-Netz braucht, um die Nachricht an das Endgerät zu übergeben und eine Quittung zurückzuliefern. Da Letztere unbegrenzt und der Kontrolle des Absenders entzogen ist, quittiert eine gut entworfene API sofort (202) mit einem accepted- oder queued-Zustand und stellt das Endergebnis anschließend asynchron zu — ein Delivery-Status-Callback (das HTTP-Pendant einer SMPP-Zustellquittung). Clients, die den Endzustand benötigen, abonnieren entweder den Callback (Push) oder pollen GET /messages/{id} (Pull); der Callback ist vorzuziehen, weil er Poll-Last vermeidet und Zustandsänderungen innerhalb von Sekunden meldet.
HTTP/1.1 202 Accepted
Location: /v1/messages/01HZY8Q3M6
Content-Type: application/json
{
"id": "01HZY8Q3M6",
"status": "accepted",
"created_at": "2026-07-19T09:15:22Z",
"status_url": "/v1/messages/01HZY8Q3M6"
}Content Negotiation und Versionierung
Clients und Server einigen sich über die Content-Negotiation-Header aus RFC 9110 auf die Repräsentation: die Anfrage trägt Content-Type für den gesendeten Body und Accept für das gewünschte Rückgabeformat, und der Server spiegelt den gewählten Media-Type im Content-Type der Response. Die meisten Messaging-APIs standardisieren auf application/json und nutzen application/problem+json für Fehler. Für die API-Versionierung gibt es zwei verbreitete Muster. Die URL-Versionierung (/v1/messages) ist explizit, cache-freundlich und trivial zu routen, allerdings um den Preis eines groben Sprungs über die gesamte Oberfläche. Die Header- oder Media-Type-Versionierung (Accept: application/vnd.example.v2+json) hält URLs stabil und lässt eine Ressource sich unabhängig weiterentwickeln, ist dafür aber im Browser unsichtbar und von Hand schwerer zu testen. Welche auch gewählt wird: additive Änderungen (neue optionale Felder) sollten nie einen Versionssprung erfordern; nur Breaking Changes tun das.
| Ansatz | Beispiel | Abwägung |
|---|---|---|
| URL-Pfad | /v1/messages | Explizit, cachefähig, einfach zu routen; grobe Versionssprünge |
| Benutzerdefinierter Header | Api-Version: 2026-07-19 | Saubere URLs, datumsgebunden; für Caches und Browser unsichtbar |
| Akzeptierter Medientyp | Accept: application/vnd.example.v2+json | Weiterentwicklung pro Ressource; manuell schwerer zu testen |
| Abfrageparameter | /messages?version=2 | Einfach; verkompliziert das Caching und die Ressourcenidentität |
REST vs. SMPP: die Wahl des Transports
Die HTTP/REST-Schicht und SMPP sind zwei Transporte auf dasselbe Messaging-Netz, und erfahrene Absender nutzen beide. REST ist die richtige Wahl für die Anwendungsintegration: es ist zustandslos, firewallfreundlich über gewöhnliches HTTPS, leicht mit einem bearer token abzusichern und einfach zu instrumentieren. SMPP ist die richtige Wahl für sehr hohen anhaltenden Durchsatz und den geringsten Overhead pro Nachricht, weil eine langlebige binäre Session die Verbindungskosten pro Nachricht vermeidet und feingranulare Window-Kontrolle bietet. Die Tabelle stellt beide gegenüber, damit ein Integrator den Transport auf die Last abstimmen kann; für BroadNets konkrete REST-Endpunkte siehe die Developer-API-Referenz und für das Wire-Protokoll den SMPP-Überblick.
| Eigenschaft | REST / HTTP | SMPP |
|---|---|---|
| Modell | Zustandslose Anfrage/Antwort über HTTPS | Zustandsbehaftete, langlebige binäre Sitzung (Bind) |
| Framing | JSON über HTTP/1.1 oder HTTP/2 | Binäre PDU (submit_sm, deliver_sm) |
| Zustellbestätigung | Status-Webhook / GET-Abfrage | deliver_sm-Quittung in derselben Sitzung |
| Durchsatz | Gut; Aufwand pro Anfrage | Höchster Dauerdurchsatz; fensterbasiert, geringer Overhead |
| Auth | Bearer-Token / API-Schlüssel / OAuth 2.0 | system_id + Passwort beim Bind |
| Flusssteuerung | 429 + Retry-After, RateLimit-Header | Fenstergröße + enquire_link-Throttling |
| Ideal für | App-Integration, Webhooks, moderates Volumen | Hochvolumige A2P-Massenströme in Carrier-Qualität |
Häufig gestellte Fragen
Warum gibt eine REST-Messaging-API 202 statt 200 oder 201 zurück?
Weil die Nachrichtenzustellung asynchron ist. RFC 9110 definiert 202 Accepted als ‚zur Verarbeitung angenommen, Verarbeitung nicht abgeschlossen‘, was einen eingereihten Versand genau beschreibt. Die API quittiert sofort mit einer Message-ID und einem Status-Handle und meldet das endgültige Zustellergebnis später per Callback. 201 und 200 implizieren, dass der Vorgang bereits abgeschlossen ist.
Wie sollte eine messages-Ressource modelliert werden?
Als Collection: POST /messages erzeugt und reiht eine Nachricht ein, GET /messages/{id} liest ihren Zustand und GET /messages listet und filtert. Der Server vergibt den Identifier und gibt ihn zurück (oft in einem Location-Header), sodass der Client ein stabiles Handle hat, um zu pollen oder mit Status-Callbacks zu korrelieren.
POST ist nicht idempotent — wie vermeidet man Doppelversand?
Man behält POST bei (es drückt korrekt ‚eine neue Nachricht erzeugen‘ aus) und macht es mit einem Idempotency-Key-Request-Header idempotent. Ein erneut gesendeter Versand mit demselben Key gibt das ursprüngliche Ergebnis zurück, statt eine zweite Nachricht zu erzeugen. PUT zu missbrauchen, um Idempotenz zu erzwingen, bricht das REST-Ressourcenmodell.
Was ist der Unterschied zwischen API-Latenz und Zustelllatenz?
Die API-Latenz ist, wie lange der HTTP-Aufruf braucht, um die Nachricht anzunehmen; die Zustelllatenz ist, wie lange das Operator-Netz braucht, um das Endgerät zu erreichen und eine Quittung zurückzuliefern. Letztere ist unbegrenzt und der Kontrolle des Absenders entzogen — deshalb quittiert die API schnell (202) und meldet die endgültige Zustellung asynchron.
Sollte ich eine Messaging-API in der URL oder in einem Header versionieren?
Die URL-Versionierung (/v1/messages) ist explizit, cache-freundlich und leicht zu routen, springt aber die gesamte Oberfläche auf einmal. Die Header- oder Media-Type-Versionierung hält URLs stabil und lässt Ressourcen sich unabhängig weiterentwickeln, ist aber für Caches unsichtbar und von Hand schwerer zu testen. In beiden Fällen sollten additive Änderungen nie einen Versionssprung erzwingen.
Wann sollte ich REST statt SMPP verwenden?
Nutze REST für die Anwendungsintegration: zustandslos, firewallfreundliches HTTPS, bearer-token-Authentifizierung und einfache Instrumentierung. Nutze SMPP für höchsten anhaltenden Durchsatz und geringsten Overhead pro Nachricht, wo sich eine langlebige, gefensterte binäre Session auszahlt. Beide erreichen dasselbe Messaging-Netz; viele Absender fahren REST für Steuerverkehr und SMPP für hochvolumige Firehoses.
Quellenspezifikationen
Diese Seite basiert auf den veröffentlichten Standards. (Wird in einem neuen Tab geöffnet.)