Power Pages Web API: Response-Verhalten bei POST-Requests

Inhalt

Einleitung
Power Pages Web API: Standardverhalten bei POST-Requests
Power Pages Web API: Representation-Szenario und Rückgabe von Daten im Response-Body
Power Pages Web API: Technische und Sicherheits-Überlegungen für Entwickler
Fazit zum Response-Verhalten der Power Pages Web API
Praxis-Erfahrungen mit Power Pages Web API POST-Response

Einleitung

Beim Erstellen von Datensätzen via OData (Web API) in Power Pages gibt es zwei primäre Szenarien für die Rückgabewerte.

Power Pages Web API: Standardverhalten bei POST-Requests

Ohne zusätzliche Konfiguration verhält sich die API “sparsam”, um Bandbreite zu optimieren.

HTTP Status: 204 No Content
Response Body: Leer.
Key Insight: Die Identität des neuen Datensatzes steckt im Header.
Extraktion der ID: Die GUID befindet sich im Response-Header entityid. In JavaScript kann diese via xhr.getResponseHeader("entityid") ausgelesen werden.

Beispiel: POST-Request mit 204 No Content

Das folgende Beispiel zeigt, wie man einen neuen Datensatz erstellt und die ID aus dem Header extrahiert:

fetch("/_api/ins_policies", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "__requestverificationtoken": token,
  },
  body: JSON.stringify({
    ins_name: "New Policy",
    // ... optional fields }),
})
  .then((response) => {
    if (response.status === 204) {
      const entityId = response.headers.get("entityid");
      console.log("Created entity ID:", entityId);
    } else {
      throw new Error(`Unexpected status code: ${response.status}`);
    }
  })
  .catch((error) => {
    console.error("Error creating policy:", error);
  });

Response-Header bei 204 No Content

Ein erfolgreicher POST-Request führt zu folgendem Response-Header:

HTTP/1.1 204 No Content
entityid: 12345678-90ab-cdef-1234-567890abcdef
odata-entityid: https://<domain>.powerappsportals.com/_api/ins_policies(12345678-90ab-cdef-1234-567890abcdef)

Das entityid Header enthält die URL zum neu erstellten Datensatz, aus der die GUID extrahiert werden kann. In diesem Beispiel wäre die ID 12345678-90ab-cdef-1234-567890abcdef.

Vorteile des Standardverhaltens der Power Pages Web API

Performance — Kein unnötiger Payload, schnellere Übertragung
Sicherheit — Keine versehentliche Exposition von Daten, die nicht benötigt werden
Klarheit — Klare Trennung zwischen Erfolg (204) und Fehlern

Power Pages Web API: Representation-Szenario und Rückgabe von Daten im Response-Body

Wenn die App die Daten des neuen Datensatzes sofort benötigt (z. B. für berechnete Felder oder zur Anzeige).

Anforderung: Header Prefer: return=representation muss im Request gesetzt sein.
HTTP Status: 201 Created
Response Body: Enthält das vollständige JSON-Objekt des erstellten Datensatzes.
Best Practice: Kombiniere dies mit $select, um nur die wirklich benötigten Spalten zurückzugeben und die Performance zu optimieren.

Beispiel: POST-Request mit 201 Created

fetch('/_api/ins_policies', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    __requestverificationtoken: token,
    Prefer: 'return=representation',
  },
  body: JSON.stringify({
    ins_name: 'New Policy',
    ins_description: 'This is a new policy created via API.',
  }),
})
  .then((response) => {
    if (response.status === 201) {
      return response.json();
    } else {
      throw new Error(`Unexpected status code: ${response.status}`);
    }
  })
  .then((createdPolicy) => {
    console.log('Created policy data:', createdPolicy);
  })
  .catch((error) => {
    console.error('Error creating policy:', error);
  });

Response-Body bei 201 Created

Ein erfolgreicher POST-Request mit Prefer: return=representation führt zu folgendem Inhalt im Response-Body

{
  "ins_policyid": "12345678-90ab-cdef-1234-567890abcdef",
  "ins_name": "New Policy",
  "ins_policynumber": "POL-001"
  // ... other fields
}

Vorteile des Representation-Szenarios

Sofortiger Zugriff auf Daten — Keine Notwendigkeit für einen zusätzlichen GET-Request
Flexibilität — Kann mit $select kombiniert werden, um nur relevante Daten zurückzugeben Einfachere Logik — Reduziert die Anzahl der API-Aufrufe, was die Fehleranfälligkeit verringert

Power Pages Web API: Technische und Sicherheits-Überlegungen für Entwickler

Bevor du die Power Pages Web API produktiv nutzt, solltest du einige technische und sicherheitsrelevante Aspekte kennen. Die folgenden Punkte helfen dir, typische Stolperfallen zu vermeiden und eine reibungslose Integration sicherzustellen:

Berechtigungen: Table Permissions (Tabellenberechtigungen) müssen explizit “Create” erlauben.
Site Settings: Die Web API muss für die jeweilige Tabelle in den Website-Einstellungen aktiviert sein.
CSRF-Schutz: Bei jedem POST-Request muss das __RequestVerificationToken mitgesendet werden.
Header-Optionen: Entscheide bewusst zwischen Standardverhalten (204) und “Representation” (201) basierend auf den Anforderungen deiner Anwendung.
Fehlerbehandlung: Implementiere robuste Fehlerbehandlung, um unerwartete Statuscodes oder fehlende Header zu erkennen und zu behandeln.

Fazit zum Response-Verhalten der Power Pages Web API

Das Standardverhalten (204 No Content) ist ideal, wenn die ID aus dem Header extrahiert werden kann und keine weiteren Daten benötigt werden.
Das “Representation” Szenario (201 Created) ist notwendig, wenn die App sofort Zugriff auf die Daten des neuen Datensatzes benötigt, z. B. für die Anzeige oder weitere Berechnungen.
Entwickler sollten die Anforderungen ihrer Anwendung sorgfältig abwägen, um die beste Option zu wählen und gleichzeitig die Performance zu optimieren.

Offizielle Dokumentation: Erstellen eines Datensatzes mit Daten im Response-Body

Praxis-Erfahrungen mit Power Pages Web API POST-Response

In meinem Fall habe ich es nicht geschafft, Power Pages dazu zu bringen, die Daten im Response-Body mit dem Status 201 Created zurückzugeben, selbst mit dem Prefer: return=representation Header. Stattdessen erhielt ich immer 204 No Content. Vermutlich ist dies eine Einschränkung aus Sicherheitsgründen oder ein festes Verhalten der Power Pages Web API, das nicht geändert werden kann und nur der Dataverse Web API vorbehalten ist, obwohl beide APIs auf OData basieren

Die erzeugten Datensätze waren jedoch immer im entityid Header enthalten, sodass ich diesen Wert extrahieren konnte, um die ID des neuen Datensatzes zu erhalten. Es ist wichtig, dass Entwickler dieses Verhalten kennen und entsprechend planen, wenn sie mit der Power Pages Web API arbeiten.

Die offizielle Microsoft-Dokumentation zu Web API Http Requests und Statuscodes bestätigt ebenfalls, dass 204 No Content das erwartete Verhalten für erfolgreiche POST-Requests ist, wenn keine Daten zurückgegeben werden. Es gibt keine Erwähnung von 201 Created oder der Möglichkeit, Daten im Response-Body zurückzugeben, was darauf hindeutet, dass dies tatsächlich das richtige Verhalten der Power Pages Web API ist.