1"use strict";(globalThis.webpackChunkschulconnex=globalThis.webpackChunkschulconnex||[]).push([[9589],{2103(e,n,r){r.r(n),r.d(n,{assets:()=>l,contentTitle:()=>u,default:()=>c,frontMatter:()=>a,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"schnittstellendefinition/bundling-qs","title":"B\xfcndelung mehrerer API-Anfragen","description":"Wenn ein Quellsystem eine gro\xdfe Zahl von API-Anfragen an den Server schickt, kann es zu \xdcbertragungsengp\xe4ssen kommen, da bei HTTP 1.x f\xfcr jeden Aufruf eine eigene Verbindung aufgebaut wird, was einen hohen Organisationsoverhead verursacht.","source":"@site/docs/schnittstellendefinition/bundling-qs.md","sourceDirName":"schnittstellendefinition","slug":"/schnittstellendefinition/bundling-qs","permalink":"/docs/schnittstellendefinition/bundling-qs","draft":false,"unlisted":false,"tags":[{"inline":true,"label":"Informativ","permalink":"/docs/tags/informativ"}],"version":"current","frontMatter":{"title":"B\xfcndelung mehrerer API-Anfragen","tags":["Informativ"]},"sidebar":"spezQuellsystemeSidebar","previous":{"title":"Validierung","permalink":"/docs/schnittstellendefinition/validierung-qs"},"next":{"title":"Autorisierung und Authentifizierung","permalink":"/docs/schnittstellen/autorisierung-qs"}}');var t=r(74848),s=r(28453);const a={title:"B\xfcndelung mehrerer API-Anfragen",tags:["Informativ"]},u="B\xfcndelung mehrerer API-Anfragen",l={},d=[{value:"HTTP/2 oder HTTP/3",id:"http2-oder-http3",level:2},{value:"JSON-Batching",id:"json-batching",level:2},{value:"Strukturierung mehrerer Anfragen",id:"strukturierung-mehrerer-anfragen",level:2}];function o(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",header:"header",p:"p",pre:"pre",...(0,s.R)(),...e.components},{Details:r}=n;return r||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"b\xfcndelung-mehrerer-api-anfragen",children:"B\xfcndelung mehrerer API-Anfragen"})}),"\n",(0,t.jsx)(n.p,{children:"Wenn ein Quellsystem eine gro\xdfe Zahl von API-Anfragen an den Server schickt, kann es zu \xdcbertragungsengp\xe4ssen kommen, da bei HTTP 1.x f\xfcr jeden Aufruf eine eigene Verbindung aufgebaut wird, was einen hohen Organisationsoverhead verursacht."}),"\n",(0,t.jsx)(n.p,{children:"Eine solche Situation kann beispielsweise auftreten, wenn am Anfang oder am Ende eines Schuljahres die Personen- und Personenkontextdaten aller Lehrenden und Lernenden einer gro\xdfen Schule, sowie deren Zugeh\xf6rigkeit zu Gruppen, synchronisiert werden sollen."}),"\n",(0,t.jsx)(n.h2,{id:"http2-oder-http3",children:"HTTP/2 oder HTTP/3"}),"\n",(0,t.jsx)(n.p,{children:"Ein Betreiber eines Schulconnex-Servers kann statt oder zus\xe4tzlich zu HTTP/1.x als Protokoll auch HTTP/2 oder HTTP/3 anbieten. Beide Protokolle erlauben die Zusammenfassung (Multiplexing) mehrerer API Anfragen \xfcber dieselbe Verbindung, so dass der zus\xe4tzliche Zeitaufwand zum Verbindungsaufbau bei mehreren Anfragen entf\xe4llt."}),"\n",(0,t.jsx)(n.p,{children:"Ob ein Schulconnex-Server die Protokolle HTTP/2 oder HTTP/3 mit Multiplexing unterst\xfctzt, ist beim jeweiligen Betreiber des Schulconnex-Servers nachzufragen."}),"\n",(0,t.jsx)(n.h2,{id:"json-batching",children:"JSON-Batching"}),"\n",(0,t.jsxs)(n.p,{children:["Eine weitere M\xf6glichkeit f\xfcr Betreiber eines Schulconnex-Servers eine gro\xdfe Menge von API-Aufrufen mit wenigen Anfragen zu erm\xf6glichen, ist die Bereitstellung eines Batch-Endpunktes, wie er beispielsweise bei ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/graph/json-batching",children:"Microsoft Graph"})," beschrieben ist."]}),"\n",(0,t.jsxs)(n.p,{children:["Dieser API-Endpunkt hat den Namen ",(0,t.jsx)(n.code,{children:"$batch"}),", also beispielsweise ",(0,t.jsx)(n.code,{children:"https://schulconnex.test/v1/$batch"})," und erlaubt als HTTP-Methode nur POST."]}),"\n",(0,t.jsxs)(n.p,{children:["Der Body der Anfrage besteht aus dem JSON-Objekt ",(0,t.jsx)(n.code,{children:"requests"}),", das eine Liste von API-Aufrufen enth\xe4lt."]}),"\n",(0,t.jsxs)(n.p,{children:["Jeder Aufruf in der Liste enth\xe4lt eine ID, um den Aufruf zu identifizieren, die URL der aufgerufenen API ohne Server- und Versionsnamen (also beispielsweise ",(0,t.jsx)(n.code,{children:"/v1/personenkontext/123454/beziehungen"})," zum Zugriff auf Beziehungen zu Personenkontext 123454), die zu verwendende HTTP-Methode (in dem Beispiel ",(0,t.jsx)(n.code,{children:"POST"}),", um eine Beziehung anzulegen, oder ",(0,t.jsx)(n.code,{children:"GET"}),", um existierende Beziehungen auszulesen), gefolgt von einem JSON-Objekt mit dem Body des Requests bei ",(0,t.jsx)(n.code,{children:"POST-"})," oder ",(0,t.jsx)(n.code,{children:"DELETE-"}),"Aufrufen."]}),"\n",(0,t.jsxs)(r,{children:[(0,t.jsx)("summary",{children:"Beispiel JSON-Batch-Request (einklappen/ausklappen)"}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-jsx",children:'{\n "requests": [\n {\n "id": "1",\n "url": "/v1/personen",\n "method": "POST",\n "headers": {\n "Content-Type": "application/json"\
1n },\n "body": {\n "referrer": "125",\n "name": {\n "familienname": "von Musterfrau",\n "vorname": "Natalie",\n "initialenfamilienname": "M",\n "initialenvorname": "N",\n "rufname": "Nat",\n "sortierindex": "4"\n },\n "geburt": {\n "datum": "2018-05-01",\n "geburtsort": "Berlin, Deutschland"\n },\n "geschlecht": "w",\n "lokalisierung": "de",\n "vertrauensstufe": "Teil",\n "auskunftssperre": "Nein"\n }\n },\n {\n "id": "2",\n "url": "/v1/personen",\n "method": "POST",\n "headers": {\n "Content-Type": "application/json"\n },\n "body": {\n "referrer": "126",\n "name": {\n "familienname": "Naur",\n "vorname": "Sebastian ",\n "initialenfamilienname": "N",\n "initialenvorname": "S",\n "rufname": "Bastian",\n "sortierindex": "0"\n },\n "geburt": {\n "datum": "2018-02-04",\n "geburtsort": "Hamburh, Deutschland"\n },\n "geschlecht": "m",\n "lokalisierung": "de",\n "vertrauensstufe": "Teil",\n "auskunftssperre": "Nein"\n }\n },\n {\n "id": "3",\n "url": "/v1/personen",\n "method": "POST",\n "headers": {\n "Content-Type": "application/json"\n },\n "body": {\n "referrer": "127",\n "name": {\n "familienname": "Boschke",\n "vorname": "Susanne",\n "initialenfamilienname": "B",\n "initialenvorname": "S",\n "rufname": "Susi",\n "sortierindex": "0"\n },\n "geburt": {\n "datum": "2018-07-11",\n "geburtsort": "Berlin, Deutschland"\n },\n "geschlecht": "w",\n "lokalisierung": "de",\n "vertrauensstufe": "Teil",\n "auskunftssperre": "Nein"\n }\n }\n ]\n}\n'})})]}),"\n",(0,t.jsx)(n.p,{children:"Die Resultate der API-Aufrufe werden dann vom Server in einem Batch-Response-Objekt zur\xfcckgeliefert."}),"\n",(0,t.jsxs)(r,{children:[(0,t.jsx)("summary",{children:"Beispiel JSON BATCH Response (einklappen/ausklappen)"}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-jsx",children:'{\n "responses": [\n {\n "id": "1",\n "status": 201,\n "headers": {\n "Cache-Control": "no-cache",\n "Content-Type": "application/json;charset=utf-8"\n },\n "body": {\n "id": "b56a5848-4bcc-4936-b43c-56cf55fd7965",\n "mandant": "58f45270-8e54-40c6-a212-980307fc19be",\n "revision": "1",\n "referrer": "125",\n "name": {\n "familienname": "von Musterfrau",\n "vorname": "Natalie",\n "initialenfamilienname": "M",\n "initialenvorname": "N",\n "rufname": "Nat",\n "sortierindex": "4"\n },\n "geburt": {\n "datum": "2018-05-01",\n "geburtsort": "Berlin, Deutschland"\n },\n "geschlecht": "w",\n "lokalisierung": "de",\n "vertrauensstufe": "Teil",\n "auskunftssperre": "Nein"\n }\n },\n {\n "id": "2",\n "status": 201,\n "headers": {\n "Cache-Control": "no-cache",\n "Content-Type": "application/json;charset=utf-8"\n },\n "body": {\n "id": "c59a96ce-2613-47b8-b365-08ff3eb3d0ee",\n "mandant": "58f45270-8e54-40c6-a212-980307fc19be",\n "revision": "1",\n "referrer": "126",\n "name": {\n "familienname": "Naur",\n "vorname": "Sebastian ",\n "initialenfamilienname": "N",\n "initialenvorname": "S",\n "rufname": "Bastian",\n "sortierindex": "0"\n },\n "geburt": {\n "datum": "2018-02-04",\n "geburtsort": "Hamburh, Deutschland"\n },\n "geschlecht": "m",\n "lokalisierung": "de",\n "vertrauensstufe": "Teil",\n "auskunftssperre": "Nein"\n }\n },\n {\n "id": "3",\n "status": 201,\n "headers": {\n "Cache-Control": "no-cache",\n "Content-Type": "application/json;charset=utf-8"\n },\n "body": {\n "id": "4f799ba2-eb43-4230-ad64-083d72488caa",\n "mandant": "58f45270-8e54-40c6-a212-980307fc19be",\n "revision": "1",\n "referrer": "127",\n "name": {\n "familienname": "Boschke",\n "vorname": "Susanne",\n "initialenfamilienname": "B",\n "initialenvorname": "S",\n "rufname": "Susi",\n "sortierindex": "0"\n },\n "geburt": {\n "datum": "2018-07-11",\n "geburtsort": "Berlin, Deutschland"\n },\n "geschlecht": "w",\n "lokalisierung": "de",\n "vertrauensstufe": "Teil",\n "auskunftssperre": "Nein"\n }\n }\n ]\n}\n'})})]}),"\n",(0,t.jsxs)(n.p,{children:["Es ist dem Betreiber eines Schulconnex-Servers freigestellt, ob ein API-Endpunkt ",(0,t.jsx)(n.code,{children:"$batch"})," bereitgestellt wird."]}),"\n",(0,t.jsx)(n.p,{children:"Ein solcher API-Endpunkt erfordert, anders als HTTP/2 oder HTTP/3 Multiplexing, mehr Aufwand in der Bereitstellung. Er erm\xf6glicht dem Schulconnex-Server jedoch weitere Optimierungen, zus\xe4tzlich zur Einsparung beim Verbindungsaufbau, beispielsweise durch die interne Zusammenfassung mehrerer Personenkontexte in einem einzelnen Datenbankaufruf."}),"\n",(0,t.jsx)(n.h2,{id:"strukturierung-mehrerer-anfragen",children:"Strukturierung mehrerer Anfragen"}),"\n",(0,t.jsx)(n.p,{children:"Weder HTTP Multiplexing noch JSON-Batching erlaubt die direkte Nutzung von R\xfcckgabewerten vorheriger Aufrufe. Daher kann beispielsweise nicht in einem Aufruf ein Personen
1datensatz und ein dazu geh\xf6render Personenkontext erstellt werden, da die ID des Personendatensatz ben\xf6tigt wird, um den Personenkontext zu erstellen."}),"\n",(0,t.jsx)(n.p,{children:"Beispielsweise sollten in einem Aufruf erst alle Personendatens\xe4tze f\xfcr eine Schule angelegt werden, die resultierenden IDs gesammelt und anschlie\xdfend in einem zweiten Aufruf alle Personenkontexte erstellt werden.\u201c"}),"\n",(0,t.jsx)(n.p,{children:"Entsprechend sollte auch mit Gruppen und Gruppenzugeh\xf6rigkeiten verfahren werden."})]})}function c(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(o,{...e})}):o(e)}},28453(e,n,r){r.d(n,{R:()=>a,x:()=>u});var i=r(96540);const t={},s=i.createContext(t);function a(e){const n=i.useContext(s);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function u(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:a(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.