Transcript CodeJam OnderwijsDataAPI.key

http://www.egeniq.com
[email protected]
@egeniq
OnderwijsDataAPI
Introductie / Demo
Ivo Jansch
Code Jam Apps in onderwijs & onderzoek, 13-2-2014
Wie ben ik?
@ijansch
Entreprenerd
Mobile & Web Developer
Auteur / Spreker
!
!2
Over Egeniq
Mobile
Development
Kennis
Nieuwe Werken
!
!
!
!
!
!
!3
Ervaring met Onderwijs Apps
!4
Doel project
Implementatie van werkende API op basis van
het OnderwijsData project
!
https://wiki.surfnet.nl/display/onderwijsdata/APIs
!5
Doel project
Voordelen API standaardisatie:
!
•
•
•
•
Niet het wiel in elke instelling opnieuw uitvinden
Samenwerking
Gemak
One API To Rule Them All
!6
Deliverables
•
Gewenste deliverables:
• Referentie API implementatie
• Demo app in HTML5
• Client libraries
!
•
Eisen:
• Alle deliverables gedocumenteerd
• Open Source
!7
Stap 1: API
!8
API specificatie
•
•
•
REST API
JSON
OAuth2
!9
Referentie Implementatie
•
•
•
•
•
Ontwikkeld in Python
Django Framework als basis
Django Rest Framework voor de API
Django Rest Swagger voor automatische
documentatie
VirtualEnv voor eenvoudige, standalone
runtime om makkelijk te testen
!10
9 APIs geimplementeerd
•
•
•
•
•
•
•
•
Studievoortgang
Tentamen resultaten
Gebouwen/kamers/werkplekken
Cursus informatie
Groepen
Gebruikersinformatie
Roosters (kamers, lessen, personen)
Telefoongids
!11
Demo: API omgeving
!12
Gebruik van de API - Basis
http://<server>/persons
=> Lijst van personen
http://<server>/persons/3
=> 1 specifieke persoon
http://<server>/persons/3/schedule
=> rooster van persoon
!13
Gebruik van de API - Filters
http://<server>/persons?page=3
=> paginatie
!
http://<server>/persons/2/schedule?
start=1997-07-18T07:00:00Z
&end=1997-07-18T23:00:00Z
=> schedule van een dag
!14
Gebruik van de API - Filters
!
http://<server>/persons?q=piet
=> search
!
http://<server>/persons/@me
=> gegevens van ingelogde gebruiker
!
!15
Gebruik van de API - Output format
!
http://<server>/persons
=> default in browser: HTML
!
curl -H "Accept:application/json" http://<server>/persons
=> JSON
!
!16
API responses
Metadata
url
Data
!17
API responses
Relaties
‘Nested objects’
Details
!18
Test Data
•
•
•
Referentie implementatie bevat test data
Beperkte set
Sommige scenario’s zijn puur demo (e.g.
search, @me werken wel, maar niet echt)
!19
Stap 2: API Clients
!20
Doel API Clients
•
•
•
Abstractie van de API
Gebruikmaken van constructies die
developer herkent
Geen zorgen over API zelf
!
•
Voorbeelden:
• Facebook SDK
• Google Analytics library
!21
API Clients
3 varianten:
!
JavaScript
• voor HTML5 apps
• Java
• voor native Android apps
• J2EE applicaties
• Objective-C
• voor native iOS apps
•
!22
JavaScript Client
<script src="onderwijsdata.min.js" type="text/
javascript"></script>
!
<script>
var onderwijsData = new Surfnet.OnderwijsData("http://localhost:8000");
var personClient = onderwijsData.createPersonClient();
!
personClient.getList(function (error, data) {
if (data != null) {
// do something with the data
}
})
</script>
!23
JavaScript Client
<script src="onderwijsdata.min.js" type="text/
javascript"></script>
!
<script>
var onderwijsData = new Surfnet.OnderwijsData("http://localhost:8000");
var personClient = onderwijsData.createPersonClient();
!
personClient.getList(function (error, data) {
if (data != null) {
// do something with the data
}
})
‘asynchrone callback’
</script>
!24
JavaScript Client
personClient.getList(params, callback)
!
Voorbeeld:
personClient.getList({q: “piet"},function
(error, data) {
if (data != null) {
// do something with the data
}
})
!25
JavaScript Client
Twee varianten voor ophalen individuele objecten:
!
getById(id, params, callback)
get(url, params, callback)
!
Voorbeelden:
!
personClient.getById(1, function(error, data){
});
personClient.get(‘http…/persons/1’, function(…){
});
!26
Java Client
•
Eenvoudige integratie:
• Voeg ‘oda.jar’ toe aan project
• Code vergelijkbaar met JS versie
!27
Java Client
final OnderwijsDataAPI apiClient = new OnderwijsDataAPI(“http://localhost:
8000”);
!
apiClient.getPersonsClient().getById("1", null, new EntityHandler<Person>() {
!
@Override
public void success(Person person) {
// display the name of the first person
firstPerson.setText("The first person is called: " person.getDisplayName());
}
!
@Override
public void failure(NetworkError e) {
// if an error happened, inform the user
e.printStackTrace();
firstPerson.setText("Error in getting first person :-(");
}
});
!28
iOS Client
•
Work in progress
• Als JavaScript/Java versies wat stabieler
zijn volgt iOS port.
!29
Stap 3: Demo applicatie
!30
Demo applicatie
Doel:
• Demonstratie alle features API/clients
• Startpunt voor verdere ontwikkeling
• Gedocumenteerd
!
Kenmerken:
• HTML5
• ‘Handlebar’ templates
!31
Demo applicatie
!32
Demo: HTML5 app
!33
Demo: Android app
!34
Geavanceerd: OAuth2
!35
OAuth2 implementatie
API ondersteunt OAuth2 voor authenticatie
• (Zie presentatie Boy Baukema elders in
het programma voor uitleg OAuth2)
• Oauth2 login flow zelf valt buiten scope van
de clients/referentie implementatie
•
!36
OAuth2 flow voorbeeld - JavaScript client
Pseudocode:
!
token = doe_oauth2_login_via_surfconnext()
!
var onderwijsData = new Surfnet.OnderwijsData(“http://
localhost:8000”, token);
=> verder ‘business as usual’
!37
OAuth2 flow voorbeeld - API zelf
OAuth2 authenticatie via ‘Bearer Token’
!
curl -H “Authorization Bearer: <token>”
“http://localhost:8000/persons/@me”
!38
Advanced: Same Origin Policies
!39
Same Origin Policy
Web-app
API
http://mijn.demoschool.nl
http://api.scholengroep.com
Browser
!40
Same Origin Policy
Web-app
API
http://mijn.demoschool.nl
http://api.scholengroep.com
Access-Control-Allow-Origin:
mijn.demoschool.nl
Browser
!41
Same Origin Policy
Web-app
http://mijn.demoschool.nl
API
Proxy
http://api.scholengroep.com
Browser
!42
Open Source ontwikkeling
“social coding”
!43
Open Source OnderwijsDataAPI
Maak een fork:
!
!
!
!
!
!44
Open Source OnderwijsDataAPI
Na wijziging, maak een ‘pull request’.
!45
“Social Coding”
!46
Resources
•
Referentie implementatie:
•
•
https://github.com/BasZoetekouw/OpenOnderwijsAPI
Clients:
•
https://github.com/egeniq/OpenOnderwijsAPI-js
•
https://github.com/egeniq/OpenOnderwijsAPI-java
•
https://github.com/egeniq/OpenOnderwijsAPI-ios
!
(worden nog verplaatst naar surfnet account)
!47
http://www.egeniq.com
[email protected]
@egeniq
Vragen?
http://www.egeniq.com
[email protected]
@ijansch