1"use strict";(globalThis.webpackChunkschulconnex=globalThis.webpackChunkschulconnex||[]).push([[7527,8400],{28453(e,n,t){t.d(n,{R:()=>l,x:()=>d});var i=t(96540);const s={},r=i.createContext(s);function l(e){const n=i.useContext(r);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:l(e.components),i.createElement(r.Provider,{value:n},e.children)}},46678(e,n,t){t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>d,default:()=>h,frontMatter:()=>l,metadata:()=>i,toc:()=>o});const i=JSON.parse('{"id":"schnittstellen/schnittstellen","title":"schnittstellen","description":"Die von Schulconnex-Servern bereitgestellten Endpunkte sind als REST-API realisiert.","source":"@site/docs/schnittstellen/schnittstellen.md","sourceDirName":"schnittstellen","slug":"/schnittstellen/","permalink":"/docs/schnittstellen/","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{}}');var s=t(74848),r=t(28453);const l={},d=void 0,c={},o=[{value:"API-Versionierung",id:"api-versionierung",level:2},{value:"Registrierung",id:"registrierung",level:2},{value:"Vorbedingungen der Schnittstelle",id:"vorbedingungen-der-schnittstelle",level:2}];function u(e){const n={a:"a",blockquote:"blockquote",code:"code",h2:"h2",p:"p",strong:"strong",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.p,{children:"Die von Schulconnex-Servern bereitgestellten Endpunkte sind als REST-API realisiert."}),"\n",(0,s.jsx)(n.p,{children:"Allgemein erfolgen Zugriffe auf Ressourcen \xfcber die Endpunkte mit Hilfe von CRUD-Operationen\n(CREATE, READ, UPDATE und DELETE). Welche Zugriffe jeweils erlaubt sind und welche\nHTTP(S)-Methoden dabei genutzt werden d\xfcrfen, ist bei den Endpunktbeschreibungen im Detail\naufgef\xfchrt. Dort werden auch die zu verwendenen JSON-Strukturen beschrieben."}),"\n",(0,s.jsx)(n.h2,{id:"api-versionierung",children:"API-Versionierung"}),"\n",(0,s.jsx)(n.p,{children:"Die URL der Schnittstelle besteht aus einer Base-URL sowie dem eigentlichen Endpunkt."}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"https://subdomain.domain.org/subpaths/endpunkt"})})}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Es wird empfohlen, unterschiedliche Versionen der Schnittstelle \xfcber unterschiedliche Endpunkte\nanzubieten. Die API-Versionierung erm\xf6glicht es den Entwicklern eines Schulconnex-Servers,\nAnpassungen an der API zu implementieren und gleichzeitig zu gew\xe4hrleisten, dass Clients mit\naktiver API-Anbindung weiterhin fehlerfrei funktionieren. Zus\xe4tzlich wird gew\xe4hrleistet, dass\nClients genug Zeit zur Implementierung einer neuen Version der API erhalten."}),"\n",(0,s.jsx)(n.p,{children:"Die Versionierung der API befindet sich in der URL zur REST-API. Dabei wird die Versionsnummer\nder API in der URL als Pfad am Ende der Base-URL mit angegeben."}),"\n",(0,s.jsxs)(n.p,{children:["Beispiel: ",(0,s.jsx)(n.code,{children:"base-url/v1/..."}),", wobei hier \u201ev1\u201c fu\u0308r die API-Versionsnummer 1.0 steht. Eine\nmo\u0308gliche API-Version 1.1 oder 2.0 wird wie folgt aufgerufen: ",(0,s.jsx)(n.code,{children:"base-url/v1-1/..."})," bzw. ",(0,s.jsx)(n.code,{children:"base-url/v2/..."}),"."]}),"\n",(0,s.jsx)(n.p,{children:"Im Folgenden ist ein Beispiel einer Schnittstellen-URL dargestellt."}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"https://subdomain.domain.org/subpath/v1/organisation-info"})})}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Die konkrete URL fu\u0308r die Schnittstelle erhalten Sie von dem Betreiber des Schulconnex-Servers."}),"\n",(0,s.jsx)(n.h2,{id:"registrierung",children:"Registrierung"}),"\n",(0,s.jsx)(n.p,{children:"Gem\xe4\xdf der Spezifikation OAuth muss ein Dienst oder ein Quellsystem (Client-Anwendung) gegen\xfcber\nSchulconnex bekannt sein. Diesbez\xfcglich wird die Client-Anwendung \xfcber einen organisatorischen\nProzess registriert."}),"\n",(0,s.jsx)(n.p,{children:"Durch die Registrierung wird dem Quellsystem eine Client-ID und das dazugeh\xf6rige Client Secret\nzur Verf\xfcgung gestellt."}),"\n",(0,s.jsx)(n.h2,{id:"vorbedingungen-der-schnittstelle",children:"Vorbedingungen der Schnittstelle"}),"\n",(0,s.jsx)(n.p,{children:"Generell gilt f\xfcr alle Anfragen an die API folgende Vorbedingung:"}),"\n",(0,s.jsxs)(n.p,{children:["Jede API Request muss einen Authorization-Header haben. Der Authorization-Header setzt sich aus\n",(0,s.jsx)(n.code,{children:"token_type"})," und dem eigentlichen ",(0,s.jsx)(n.code,{children:"access_token"})," zusammen. Im Kontext der Spezifikation \u201e",(0,s.jsx)(n.a,{href:"https://openid.net/specs/openid-connect-core-1_0.html",children:"OpenID Connect"}),"\u201c\nmuss das Attribut ",(0,s.jsx)(n.code,{children:"token_type"})," den Wert \u201eBearer\u201d f\xfchren."]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:["Format: ",(0,s.jsx)(n.code,{children:"Authorization: {token_type} {access_token}"})]}),"\n"]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:["Beispiel: ",(0,s.jsx)(n.code,{children:"Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpJ9.e..."})]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["Es wird empfohlen, den zu erwartenden Content-Type explizit als ",(0,s.jsx)(n.code,{children:"application/json"})," anzugeben.\nWird kein Content-Type gesetzt, wird automatisch ",(0,s.jsx)(n.code,{children:"application/json"})," angenommen."]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.code,{children:"Accept: application/json"})}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(u,{...e})}):u(e)}},71705(e,n,t){t.r(n),t.d(n,{assets:()=>o,contentTitle:()=>c,default:()=>a,frontMatter:()=>d,metadata:()=>i,toc:()=>u});const i=JSON.parse('{"id":"schnittstellen/schnittstellen-dienste","t
1itle":"Nutzung der REST-API","description":"","source":"@site/docs/schnittstellen/schnittstellen-dienste.md","sourceDirName":"schnittstellen","slug":"/schnittstellen/schnittstellen-dienste","permalink":"/docs/schnittstellen/schnittstellen-dienste","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"title":"Nutzung der REST-API"},"sidebar":"spezDiensteSidebar","previous":{"title":"Verwaltungspolitische Kodierung","permalink":"/docs/datenmodell-dienste/verwaltungspolitischeKodierung"},"next":{"title":"Schnittstellendefinition","permalink":"/docs/schnittstellendefinition/schnittstellendefinition-dienste"}}');var s=t(74848),r=t(28453),l=t(46678);const d={title:"Nutzung der REST-API"},c=void 0,o={},u=[...l.toc];function h(e){return(0,s.jsx)(l.default,{})}function a(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(h,{...e})}):h()}}}]);
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.