REST i Ladok3

1. REST i Ladok3 • Jan Stenberg, Knowit • Senior arkitekt i Ladok3 2013-10-23

2. Agenda • Introduktion • Bakgrund • Valet av REST för Ladok3 • REST-principer • REST i Ladok3 • Ladok3:s arkitektur • Exempel, REST - Ladok3 • Summering

3. Introduktion • Ladok3 har valt REST • Ett gemensamt gränssnitt för Ladok3 • Externt och internt • Användargränssnitt • Webbaserat mot användare, REST internt • Web API för lärosäten

4. Bakgrund • Web Services, WS, var ett paradigmskifte när det kom • Vi gick från proprietäraprotokoll som DCOM, RMI och CORBA, (som var standardiserade på papperet men inte i verkligheten), till integration med XML och standard-protokoll. • Men… • WS använder bara en del av http-protokollet, för transport. • WS beskriver bara enskilda operationer. • Ger ett beroende mellan klient och server • REST kan beskriva ett flöde.

5. Valet av REST för Ladok3 • REST har många fördelar • Plattformsoberoende • Lösa kopplingar • Skalbarhet, en eller flera servers • Enkelhet • Utvecklas snabbt mot att bli ”standard” för ett Web API • Och få nackdelar • Relativt nytt • Vi kan inte automatgenerera kod för kommunikationen • Inga reella alternativ, (SOAP, CORBA, DCOM, Java RMI)

6. Förändringar mot dagens Ladok

7. Webben som applikationsplattform • Världens största distribuerade informationssystem • ”Alla” plattformar • Prestanda • Stateless - lätt att replikera • Skalbarhet - Internet-scale • Löst kopplat, allt måste inte vara igång • Ladok3:s plattform (idémässigt)

8. HTTP • Hypertext Transfer Protocol • Protokollet för webben • url • http • html • Ett applikationsprotokoll, (inte bara ett transportprotokoll) • Header som beskriver ett meddelande • Body med själva meddelandet

9. HTTP-meddelanden Request: Header: GET /studiedeltagande/student/... HTTP/1.1 Accept: application/vnd.ladok+xml Response: Header: Body: HTTP/1.1 200 OK Content-Type: application/vnd.ladok+xml Date: Wed, 23 Oct2013 14:45:44 GMT <?xml version="1.0" encoding="UTF-8"?> ...

10. HTTP-metoder • GET • Hämtar en representation av en resurs • Inga sidoeffekter, ”idempotent” • POST • Skapar en ny resurs, utökar en resurs • Servern skapar URI • Skapar nya resurser • PUT • Uppdaterar en känd resurs, ”idempotent” • DELETE • Ta bort en resurs , ”idempotent”

11. Statuskoder • HTTP/1.1 200 OK • 1xx: Informational: Requestreceived, continuingprocess • 2xx: Success: The action was successfully received, understood, and accepted • 3xx: Redirection: Furtheraction must be taken in order tocomplete the request • 4xx: Clienterror: The requestcontainsbad syntax or cannot be fulfilled • 5xx: Server error: The server failedtofulfill anapparently valid request

12. REpresentional State Transfer UNIVERSITY OF CALIFORNIA, IRVINE Architectural Styles and the Design of Network-based Software Architectures DISSERTATION submitted in partial satisfaction of the requirements for the degree of DOCTOR OF PHILOSOPHY in Information and Computer Science by Roy Thomas Fielding 2000

13. Ett exempel • amazon.com • Webbplatsen leder mig genom ett flöde när jag lägger en order • Adress • Leveranssätt • Betalning • Sammanställning, lägg order

14. Resurs • Vad som helst i ett system som en konsument kan interagera med: Information • Dokument • Webbsidor • Kurs • Kaffemaskin • Transaktioner • Avstånd mellan två punkter

15. Uniform ResourceIdentifier, URI • Identifierar en resurs, skiljer en resurs från en annan • En resurs kan ha flera identifierare / URI:er • En URI kan också vara en adress till resursen, en URL, som ger åtkomst till resursen • Exempel https://api.ladok.se/utbildningsinformation/kurs/4b5c041-...-800200c9a66 uuid: 4b5c0410-a68c-11e2-9e96-0800200c9a66

16. Representation • En representation av tillståndet på en resurs vid en viss tidpunkt • På webben utbyter man representationer, aldrig den underliggande resursen • Formatet på en representation beror på klientens önskemål: html, xml, json, etc. • En resurs har samma adress, URL, oberoende av typ av representation

17. Exempel på representationer <Student> <Uid>71391050-2c39-11e3-8224-0800200c9a66</Uid> <Personnummer>19820117-9283</Personnummer> <Efternamn>Ålandsson</Efternamn> <Fornamn>Örjan</Fornamn> </Student> { "Uid":"71391050-2c39-11e3-8224-0800200c9a66", "Personnummer":"19820117-9283", "Efternamn":"Ålandsson” "Fornamn":"Örjan"}

18. Länkar • Länkar bygger upp webben • Representationer kan innehålla länkar, (URL:er) • Länkar pekar på andra resurser. • I ett studiedeltagande finns en länk till studenten • Länkar visar på möjligheter för tillståndsförändringar • I REST är länkar opaka, dvs. de ska inte tolkas <Studiedeltagande> <linkuri="http://api.ladok.se/studentinformation/student/d22…ef03" /> … </Studiedeltagande>

19. Hypermedia • Hypermedia = länkar mellan information/media • Länkar skapar ett hypermedia-format • HATEOASHypermedia As The Engine Of Application State • En klient följer länkar som en tjänst levererar i representationer • Applikationen drivs framåt genom övergång från ett tillstånd till ett annat • När applikationen når ett nytt tillstånd presenterar den vilka nya tillståndsövergångar som är möjliga

20. Relationer • Ger semantik till en länk • Vad länken betyder • Varför en klient ska följa länken <Studiedeltagande> <linkrel="student”uri="http://api.ladok.se/studentinformation/student/d22…ef03" /> … </Studiedeltagande>

21. Exempel på relationer • Standard-relationer, IANA Link Relations registry • self • previous, next • payment • Ladok3-specifika • http://relations.ladok.se/studiedeltagande/registrering • http://relations.ladok.se/studentinformation/student

22. Exempel Antagning url: http://api.ladok.se/antagning/… rel: registrering url: http://api.ladok.se/registrering/… url: http://api.ladok.se/registrering/… Skapar Deltagande rel: avbrott url: http://api.ladok.se/avbrott/…

23. Mediatyper • Mediatypen beskriver format på en representation process-modellen, vad en klient kan göraför ett specifikt representations-format • text/html, image/jpeg • Ladok3 har två mediatyper: application/vnd.ladok+xml application/vnd.ladok+json

24. Relationer, länkar och mediatyper Vadinnebärlänken: rel: VARFÖR vill jag komma åt den länkade resursen? uri: VAR finns resursen? mediaType: HUR ska jag tolka svaret? <Studiedeltagande> <linkrel="student”uri="http://api.ladok.se/studentinformation/student/d22…ef03” mediaType=”application/vnd.ladok+xml” /> … </Studiedeltagande>

25. Kontrakt • Domain Application Protocol, DAPhttp://schemas.ladok.se/dap • Utökar en mediatyp med applikationsspecifika värden på länk-relationer • Begränsar http-protokollet • Tre nyckelkomponenter • Mediatyp, ex: application/vnd.ladok+xml • Länk – relationer • Beskriver rollen för länkade resurser • http-verben • Manipulerar resurser som ingår i protokollet

26. RESTful • REST – Fullt ut • Human-webb – REST API • Utforskande • Klienten behöver inte känna till url:er • Klienten kan upptäcka nya relationer

27. REST i Ladok3 • RESTful – REST fullt ut • Använder HTTP som ett applikationsprotokoll • Hypermedia-drivet med länkar som leder klienten till andra resurser och driver tillståndsförändringar • DAP • DomainApplicationProtocol

28. Exempel • Prata REST med Ladok3

29. Dokumentation • Genereras maskinellt av tjänsterna • Kommer troligtvis att finnas både online och som nedladdningsbar fil • Innehåller text och XML-scheman https://www.mit.ladok.se/restdoc/resultat.html

30. Arkitektur för Ladok3 Studenter Examen api.ladok.se Utbildningar Deltagande <Domänhändelse>StudentEtablerad Ladok3 Resultat Behörighet

31. Multitenant • En klient till en tjänst, vårt GUI eller ett system hos ett lärosäte jobbar i kontextet av ett lärosäte. • Autentisering som visar vilket lärosäte klienten tillhör • Via Shibboleth • Via certifikat • Behörighet sätts utifrån klient. • Behörighet administreras i Ladok3

32. Referenser Böcker RESTful Web APIs REST in Practice

33. Summering • Den vanliga webben men med XML eller JSON som format och med relationer för att beskriva länkar • Resurser • Representationer • Hypermedia • Länkar • Relationer • Servernlederklienten • Ger ett oberoende mellan klient och server • Plattformsoberoende, nu och i framtiden

34. Frågor? • ?