Inloggen in "Mijn-omgeving" met Club.Dataservice
Privacygevoelige gegevens, zoals persoonsgegevens of financiële gegevens van leden, zijn alleen toegankelijk met een gebruikersnaam en wachtwoord. Artikelen die dit soort gegevens bevatten worden artikelen met een scope genoemd. Om artikelen met een scope te kunnen opvragen, moet je eerst een token verkrijgen. Hiervoor moet de gebruiker jou de toestemming geven om gegevens op te halen met een bepaalde scope. Momenteel implementeert Club.Dataservice de implicit OAuth flow. Om een token te verkrijgen moeten de volgende stappen doorlopen worden:
1. Redirect de gebruiker naar de inlog pagina met een aantal parameters:
Parameter | Uitleg |
redirect_uri | Waar de response naar moet worden terug gestuurd |
response_type | Moet "token" zijn om implicit flow aan te tonen |
client_id | De client identifier van de vereniging |
scope | Welke scopes je wilt (komma gesplitste lijst) |
state | Gebruik dit veld om de response te controleren. Club.data stuurt de gegeven waarde weer terug. Wanneer de waardes verschillen invalideert het login proces. |
Voorbeeld response wanneer de gebruiker heeft ingelogd op auth.sportlink.com:
redirect_uri/#token=gth8kj7lnf0hpn3cc9h13fcesf&token_type=bearer&scope=PERSON&expires_in=3600&state=123123
De response wordt terug gestuurd via de hash, hierdoor weet alleen de browser van het bestaan van deze key values en kan de server er niet bij. Hierdoor moet bij de implicit flow een clientside browser programmeertaal zoals JavaScript gebruikt worden om deze uit te lezen.
Response | Uitleg |
token | Token die gebruikt moet worden om data op te halen voor bepaalde scope. |
token_type | Altijd "bearer" |
scope | Welke scopes er gevraagd zijn |
expires_in | Hoelang de token geldig is in seconden |
state | Gelijk aan de opgegeven state |
2. Token meegeven
De token moet via de Authorization header worden meegegeven worden. Dit ziet er zo uit:
curl -iG https://data.sportlink.com/mijn-gegevens \
--header "Authorization: Bearer 1cki4ic3u306118ucckjps7pv6"
Errors
Errors worden via the redirect_uri als GET parameters teruggestuurd. Mogelijke error ziet er bijvoorbeeld zo uit:
Mogelijke id's zijn invalid_scope, invalid_request en server_error
Wanneer er iets fout gaat probeert Club.Data een JSON object terug te sturen met hierin informatie over de fout. Over het algemeen krijg je altijd een error in de volgende vorm:
{"error":{"message": "...","code": ...}}
De code staat vast en zal nooit veranderen. De message kan wel veranderen. Dus gebruik de code om te kijken welke error er is opgetreden. Wanneer u geen geldige JSON of een onbekende code als response krijgt, gebruik dan de HTTP status code om uw vervolg actie te bepalen. Mogelijke errors:
HTTP Code | Code | Omschrijving |
400 | 4002 | Verplicht argument is niet gegeven (zie list voor welke verplicht zijn) |
401 | 4011 | Gegeven token bestaat niet of is ongeldig |
401 | 4012 | Gegeven client_id bestaat niet of is ongeldig |
403 | 4031 | Token heeft niet de vereiste scopes om het artikel op te vragen |
404 | 4041 | Opgevraagde artikel bestaat niet. |
500 | 5001 | Server fout. Er gaat iets fout aan onze kant, dit moet onderzocht worden. |
Let op:
Een zogenoemde condition error volgt een iets ander patroon, namelijk:
{"error":{"messages":[{"id":"...","description":"..."}],"code":4001}}
In plaats van een enkel error bericht, krijg je nu een collectie van error berichten terug.