Transcript REST-gränssnittet (Jan Stenberg)

REST i Ladok3
» Jan Stenberg, Knowit
» Senior arkitekt i Ladok3
2013-10-23
Agenda
»
»
»
»
»
»
»
»
Introduktion
Bakgrund
Valet av REST för Ladok3
REST-principer
REST i Ladok3
Ladok3:s arkitektur
Exempel, REST - Ladok3
Summering
Introduktion
» Ladok3 har valt REST
» Ett gemensamt gränssnitt för Ladok3
• Externt och internt
• Användargränssnitt
o Webbaserat mot användare, REST internt
• Web API för lärosäten
Bakgrund
» Web Services, WS, var ett paradigmskifte när det kom
» Vi gick från proprietära protokoll som DCOM, RMI och
CORBA, (som var standardiserade på papperet men inte
i verkligheten), till integration med XML och standardprotokoll.
» 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.
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)
Förändringar mot dagens Ladok
Ladok
Ladok3
Webb
• LW - utdata
Webb
• Webbgränssnitt för administratör
Webbkomponenter
• TG – portlets
Webb
• Studentgränssnitt
Tjänstegränssnitt
• T – SOAP
• LP – Ping
Tjänstegränssnitt
• REST
SQL
• Direkta DB frågor/uppdateringar
SQL (enbart för läsning)
• Enbart i Uppföljning
Webben som applikationsplattform
» Världens största distribuerade informationssystem
» ”Alla” plattformar
» Prestanda
o Stateless - lätt att replikera
o Skalbarhet - Internet-scale
» Löst kopplat, allt måste inte vara igång
» Ladok3:s plattform (idémässigt)
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
HTTP-meddelanden
Request:
Header:
GET /studiedeltagande/student/... HTTP/1.1
Accept: application/vnd.ladok+xml
Response:
Header:
HTTP/1.1 200 OK
Content-Type: application/vnd.ladok+xml
Date: Wed, 23 Oct 2013 14:45:44 GMT
Body:
<?xml version="1.0" encoding="UTF-8"?>
...
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”
Statuskoder
» HTTP/1.1 200 OK
» 1xx: Informational: Request received, continuing
process
» 2xx: Success: The action was successfully received,
understood, and accepted
» 3xx: Redirection: Further action must be taken in order
to complete the request
» 4xx: Client error: The request contains bad syntax or
cannot be fulfilled
» 5xx: Server error: The server failed to fulfill an
apparently valid request
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
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
Resurs
» Vad som helst i ett system som en konsument kan
interagera med: Information
• Dokument
• Webbsidor
• Kurs
• Kaffemaskin
• Transaktioner
• Avstånd mellan två punkter
Uniform Resource Identifier, 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
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
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"
}
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>
<link uri="http://api.ladok.se/studentinformation/student/d22…ef03" />
…
</Studiedeltagande>
Hypermedia
» Hypermedia = länkar mellan information/media
» Länkar skapar ett hypermedia-format
» HATEOAS
Hypermedia 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
Relationer
» Ger semantik till en länk
• Vad länken betyder
• Varför en klient ska följa länken
<Studiedeltagande>
<link rel="student”
uri="http://api.ladok.se/studentinformation/student/d22…ef03" />
…
</Studiedeltagande>
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
Exempel
url: http://api.ladok.se/antagning/…
rel: registrering
url: http://api.ladok.se/registrering/…
Antagning
url: http://api.ladok.se/registrering/…
Skapar
rel: avbrott
url: http://api.ladok.se/avbrott/…
Deltagande
Mediatyper
» Mediatypen beskriver
format på en representation
process-modellen, vad en klient kan göra
för ett specifikt representations-format
» text/html, image/jpeg
» Ladok3 har två mediatyper:
application/vnd.ladok+xml
application/vnd.ladok+json
Relationer, länkar och mediatyper
<Studiedeltagande>
<link rel="student”
uri="http://api.ladok.se/studentinformation/student/d22…ef03”
mediaType=”application/vnd.ladok+xml” />
…
</Studiedeltagande>
Vad innebär länken:
rel:
uri:
mediaType:
VARFÖR vill jag komma åt den länkade resursen?
VAR finns resursen?
HUR ska jag tolka svaret?
Kontrakt
» Domain Application Protocol, DAP
http://schemas.ladok.se/dap
• Utökar en mediatyp med applikationsspecifika värden på länkrelationer
• Begränsar http-protokollet
» Tre nyckelkomponenter
• Mediatyp, ex: application/vnd.ladok+xml
• Länk – relationer
o Beskriver rollen för länkade resurser
• http-verben
o Manipulerar resurser som ingår i protokollet
RESTful
» REST – Fullt ut
» Human-webb – REST API
» Utforskande
» Klienten behöver inte känna till url:er
» Klienten kan upptäcka nya relationer
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
• Domain Application Protocol
Exempel
» Prata REST med Ladok3
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
Arkitektur för Ladok3
api.ladok.se
Studenter
<Domänhändelse>
StudentEtablerad
Examen
Deltagande
Utbildningar
Ladok3
Resultat
Behörighet
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
o Via Shibboleth
o Via certifikat
• Behörighet sätts utifrån klient.
• Behörighet administreras i Ladok3
Referenser
Böcker
RESTful Web APIs
REST in Practice
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
• Servern leder klienten
» Ger ett oberoende mellan klient och server
» Plattformsoberoende, nu och i framtiden
Frågor?
»?