Migreren naar partner rechten
Door de jaren heen zijn er verschillende manieren geweest om koppelingen rechten te geven. Voor een groot deel zijn die manieren gebaseerd geweest op hoe gewone gebruikers in het Zermelo Portal rechten krijgen. Daardoor is het vaak lastig om precies de juiste rechten te geven voor een koppeling.
De nieuwe Partner rechten zijn expliciet bedoeld om koppelpartijen toegang te geven tot precies de gegevens die nodig zijn voor een koppeling.
Uiteindelijk alles migreren
Het is op termijn de bedoeling dat alle koppelingen werken via partnerrechten. Voor veel koppelingen is het nu al mogelijk om over te gaan. Voor andere koppelingen zal er nog functionaliteit ontbreken. Loopt u ergens tegenaan, of ontbreekt er iets wat nodig is voor uw koppeling? Laat het ons weten!
Omdat we willen dat scholen een expliciete keuze maken welke rechten ze toekennen aan een partner, kunnen we bestaande koppelingen niet automatisch migreren. De school zal voor elke koppeling een partner aan moeten maken met de juiste rechten.
Wat gaat er veranderen?
API-versies
De API-versie gaat weg uit de URL. In plaats van /api/v3/endpoint maakt u nu gebruik van /api/endpoint. De rechten die u als partner krijgt werken alleen op dit nieuwe pad.
Tokens inwisselen en rechten inzien
Bij het aanmaken van een token krijgt de school niet langer het access_token terug, maar een authcode die eenmalig inwisselbaar is voor het token. De school stuurt deze code naar u op.
Daarnaast is er een nieuw endpoint /partners/~me waar u in kunt zien tot welke gegevens u toegang heeft.
Op Authenticatie en autorisatie staat meer uitleg en een voorbeeld. Op onze gebruikershandleiding staat uitleg voor scholen over het inrichten van een Partner.
Verplichte request parameters
De request parameters fields=... en schoolInSchoolYear=... worden op alle endpoints verplicht. Meer informatie over deze parameters vindt u op De Zermelo API
X-Impersonated-By
De impersonation header gaat er op termijn uit. In plaats daarvan is het als partner mogelijk om op /api/liveschedule requests te doen met student=X,week=Y,schoolInSchoolYear=Z. We zijn nog aan het onderzoeken hoe we de migratie voor koppelingen die nu gebruik maken van impersonation zo soepel mogelijk te maken.
Wat kan er nog niet?
Wij zijn nog druk in de weer met het uitbreiden van de mogelijkheden van het Partners-systeem. Zoals met ieder project in aanbouw, zijn er dus zaken die nog niet werken, of nog niet werken zoals we willen.
Als uw koppeling gebruik maakt van functionaliteit die nog ontbreekt, kunt u nog niet over. Wellicht is het al wel mogelijk om in uw Partner Portal te experimenteren met de functionaliteit die al wel aangeboden wordt. Houd onze API-mailing in de gaten voor uitbreidingen waardoor u misschien wel over kunt!
Voor het uitbreiden van de mogelijkheden richten wij ons in eerste instantie op de volgende zaken:
Bewerken
Momenteel is het alleen mogelijk om leesrechten te geven aan Partners. We zien inschrijven/uitschrijven via /liveschedule en gebruikersbeheer via /users als de belangrijkste endpoints om bewerken op mogelijk te maken. Als u andere uitbreidingen nodig heeft voor uw koppeling, laat het dan weten!
Endpoints ontbreken
We hebben bij het toevoegen van endpoints aan deze documentatie en het Partners-systeem gefocust op endpoints die vaker door koppelpartijen aangesproken worden. Daar zullen ongetwijfeld endpoints ontbreken.
Velden/filters zijn niet ‘Ondersteund’
We zijn terughoudend geweest in het bestempelen van velden als ‘ondersteund’ zodat we niet vastzitten aan functionaliteit waar niemand gebruik van maakt. Als u gebruik maakt van een veld wat nu als niet ondersteund te boek staat, horen wij het graag! Misschien vinden wij ook dat het ondersteund zou moeten zijn, of misschien hebben wij een alternatieve route om gegevens op te halen.