Transcript modificationDate=1368685998000;REST i Ladok3 - Umeå universitet

REST-utbildning för Ladok3
» Mikael Berglund, ITS, Umeå Universitet
» Jan Stenberg, Knowit
2013-05-15
Agenda
»
»
»
»
»
»
»
»
»
Introduktion
Bakgrund
Valet för Ladok3
Webben som en applikationsplattform
REST-principer
Atom Feeds
Ladok3 arkitektur
Att utveckla mot Ladok3
Rekommendationer
Introduktion
» Målet är att integrera mot Ladok3
» Det finns många olika tekniker
•
•
•
•
SOAP
REST
CORBA
Java RMI, Microsoft DCOM
» Ladok3 har valt REST
Bakgrund
» 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…
• SOAP är ett kuvert, vilket http också är
• SOAP hanterar http som enbart ett transportprotokoll, och
använder bara POST
• WSDL och WADL beskriver bara enskilda operationer.
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
Hypermedia
» Hypermedia = länkar mellan information/media
» Länkar skapar ett hypermedia-format
» HATEOAS
Hypermedia As The Engine Of Application State
• Applikationen drivs framåt genom övergång från ett tillstånd till
ett annat, som en State Machine
• När applikationen når ett nytt tillstånd presenterar den vilka nya
tillståndsövergångar som är möjliga
Webben som applikationsplattform
» Världens största distribuerade informationssystem,
(hypermedia-modell)
» ”Alla” plattformar
» Prestanda
o Stateless - lätt att replikera
o Skalbarhet - skalar horisontellt - Internet-scale
» Löst kopplat
» Fördröjning – Latency, > 0,5s
» Ladok3:s plattform
Aktörer på webben
Valet av REST
» Många fördelar
•
•
•
•
Skalbarhet, cache
Enkelhet
Plattformsoberoende
Lösare kopplingar
» Inget reellt 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 (individuell tilläggstjänst)
• Uppföljningslösning
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 är också en adress till resursen, ger
åtkomst till resursen
» Exempel
https://api.ladok.se/utbildningsinformation/kurs/4b5c0410-a68c-11e2-9e960800200c9a66
Representation
» En representation av tillståndet på en resurs vid en viss
tidpunkt
» På webben utbyter man representationer, aldrig den
underliggande resursen
» En representation kan bero på klientens önskemål, html,
xml, json, etc.
» En resurs har samma adress, URI, oberoende av typ av
representation
» ”By Value”, (inte by reference)
Exempel på representationer
<Student>
<Uid>00000000-0000-0000-0000-197426000000</Uid>
<Efternamn>Ålandsson</Efternamn>
<Fornamn>Örjan</Fornamn>
<Personnummer>196611010106</Personnummer>
</Student>
{
"Uid":"00000000-0000-0000-000097426000000",
"Personnummer":"196611010106",
"Fornamn":"Örjan",
"Efternamn":"Ålandsson”
}
HTTP
» Hypertext Transfer Protocol
» Ett applikationsprotokoll, (inte bara ett
transportprotokoll)
HTTP-meddelande (Request)
GET /studiedeltagande/events/recent HTTP/1.1
Accept: text/html,application/xhtml+xml,
application/xml;q=0.9,*/*;q=0.8
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64)
AppleWebKit/537.31 (KHTML, like Gecko)
Chrome/26.0.1410.64 Safari/537.31
Response
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache no-store
Content-Type: application/atom+xml
Transfer-Encoding: chunked
Date: Mon, 15 Apr 2013 06:45:44 GMT
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title type="text">
...
Uniform interface
» Alla resurser accessas på samma sätt
» Metoderna opererar på dokument
» Välkända effekter och sidoeffekter
» Statuskoder
HTTP methods
» 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
Behaviour
An action with no side
effects
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
2xx
» 200 OK
• Servern utförde begäran
» 201 Created
• Ges när klienten har anropat servern med en POST.
• Location-headern skall innehålla en URI till den skapade
resursen
• I Ladok3s fall innehåller body representationen också för er
bekvämlighet
3xx
» 301 Moved permanently
• Location-headern innehåller den nya URI:n
» 303 See other
• Location-headern innehåller den nya URI:n
• Använd GET för att hämta
• Redirect after POST
4xx
» 400 Bad request
• Klienten har gjort ett felaktigt anrop. Kan t.ex. vara felaktigt
format eller saknade parametrar
» 403 Forbidden
• Användaren är inte behörig att utföra åtgärden
• Kan vara att användaren saknar behörigheter eller inte är
inloggad
» 404 Not found
• Standard
» 409 Conflict
• Kan uppstå när man försöker skapa en ny kurs med samma kod
eller en ny student när personnumret redan finns
4xx
Utökning av http, (WebDAV)
» 422 Unprocessable Entity
• Servern förstår requesten och syntaxen är korrekt, men den kan
inte utförda åtgärden.
5xx
» 500 Internal Server Error
• När något går fel internt i Ladok3
• Se felmeddelande
• Notera UID och skicka till supporten
Länkar
» Länkar bygger upp webben
» Representationer kan innehålla URI:er (länkar)
» Länkar annonserar möjligheter för t.ex.
tillståndsförändringar
» Conversation state uttrycks med detta
» (Kom ihåg, REST, Representational state transfer)
» I REST är länkar opaka, dvs. de ska inte tolkas
• Undantaget är URI Templates, ex:
http://api.ladok3.se/studentinformation/{studentid}
Relationer
» Ger semantik till en länk
• Vad länken betyder
• Varför en klient ska följa länken
Exempel på relationer
» Standard-relationer, IANA Link Relations registry
• self
• next-archive, prev-archive
• payment
» Ladok3-specifika
• Strängkonstanter
• http://relations.ladok.se/studiedeltagande/registrering
• http://relations.ladok.se/studentinformation/student
Relationer och länkar
<dap:link rel="self“
uri="http://api.ladok3.se/studiedeltagande/28374653"
mediaType="application/vnd.ladok+xml"/>
Beskriver vad länken innebär:
rel:
VARFÖR vill jag komma åt den länkade resursen?
uri:
VAR finns resursen?
mediaType: HUR ska jag tolka svaret?
Mediatyper
» Mediatypen beskriver
schema, (format på en representation)
process-modell, (http)
(värden för länk-relationer)
för ett specifikt representations-format
» Vi har två mediatyper:
application/vnd.ladok+xml
application/vnd.ladok+json
Mediatyper
» GET /utbildningsinformation HTTP/1.1
» Host: api.ladok3.se
» Accept: application/atom+xml,application/xhtml+xml
» HTTP/1.1 200 OK
» Content-Type: application/atom+xml
» Ladok3: application/vnd.ladok+xml
application/vnd.ladok+json
Kontrakt
» Domain Application Protocol, DAP
http://schemas.ladok.se/dap
• Bygger på en mediatyp med applikationsspecifika värden på
länk-relationer
• Begränsar http-protokollet
» Tre nyckelkomponenter
• Mediatyp
• Länk – relationer
o Beskriver rollen för länkade resurser
• http-verben
o Manipulerar resurser som ingår i protokollet
DAP
» Länk-relationen gör att klienten förstår varför den ska
följa en länk
» Media-typen gör att klienten förstår vad som finns i
slutet av en länk
» HTTP-verben gör att klienten förstår hur den ska
interagera med en resurs
DAP, exempel
REST-exempel, DAP, före registrering
REST-exempel, DAP, efter registrering
REST-exempel, representation
RESTful
» REST – Fullt ut
» Human-webb – REST API
» Utforskande
» Klienten behöver inte känna till uri:er
» Klienten kan upptäcka nya relationer
REST i Ladok3
» REST – Fullt ut
•
•
•
http är ett applikationsprotokoll
Länkar som leder klienten, driver state
Web Services, SOAP, WSDL
» DAP
•
Domain Application Protocol
» Tjänstegränssnitt
•
•
Link:
Rel(ation) – Link
Action: Rel(ation) – Link – Impediment (Hinder)
Richardson Maturity Model, 1
» Nivå 0 – POX
• Använder http som ett transportprotokoll
• Bara POST
• Web Services ligger här
» Nivå 1 – Resurser
• Flera endpoints – URI:er
» Nivå 2 – http verb
• Använder http
o Alla http-verb, GET, POST, PUT, DELETE, etc.
o Statuskoder
Richardson Maturity Model, 2
» Nivå 3 – Hypermedia
• Using Hypermedia
• HATEOAS, Hypermedia As The Engine Of Application State
• Relationer och länkar som går att följa för att ändra tillstånd på
resurser
• Utforskande. Klienten behöver inte känna till uri:er utan kan
upptäcka nya relationer
• Roy Fielding: Nivå 3 är en förutsättning för REST
• RESTful Services using Hypermedia
Caching & ETags
» En viktig del av http
• Mycket information är statisk eller ändras sällan
• Kan mellanlagras på vägen från server till klienter
Last-Modified: Fri, 26 Mar 2013 09:55:15 GMT
Cache-Control: max-age=3600
• Kontrollera förändring
ETag: ″74f4be4b″
» Men inte lika viktigt i Ladok3
• I stort sett all information är behörighetskontrollerad
Dokumentation
» Genereras maskinellt av tjänsterna
» Kommer troligtvis både finnas online och som
nedladdningsbar fil
» Innehåller text och XML-scheman (.xsd)
Versionshantering
» Skilj på resurser och representationer
• Bakåtkompatibel förändring, mer information i en representation
o Ingen ny version
• Ej bakåtkompatibel förändring
o Ny version av mediatypen: application/vnd.ladok+xml;version=2
» Postel’s Law
• "An implementation should be conservative in its sending
behavior, and liberal in its receiving behavior"
• "Be liberal in what you accept, and conservative in what you
send"
Consumer Driven Contracts
» Skydda konsumenten från ändringar i kontraktet
• Producenten styrs av konsumentens förväntningar
• Använd inte scheman, XSD, för att validera XML
» Consumer-Driven Contracts: A Service Evolution Pattern
http://martinfowler.com/articles/consumerDrivenContracts.html
» A Contract Vocabulary: Part 1
http://iansrobinson.com/2008/03/27/a-contract-vocabulary-part-1/
» A Contract Vocabulary: Part 2
http://iansrobinson.com/2008/04/01/a-contract-vocabulary-part-2/
» A Contract Vocabulary: Part 3
http://iansrobinson.com/2008/04/20/a-contract-vocabulary-part-3/
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 via certifikat som visar vilket lärosäte klienten tillhör
• Behörighet sätts utifrån klient.
• Behörighet administreras i Ladok3
Multitenant /Behörighet
Arkitektur för Ladok3
Designprinciper
» Tjänsteorienterad arkitektur - Tjänsteorientering möjliggör lätt
föränderlig verksamhet. Verksamhetslogik och regler för ett område finns på
ett ställe.
» Autonoma tjänster - Med autonoma oberoende tjänster ökar
tillförlitligheten och flexibiliteten för tjänsten.
» Meddelandebaserat och händelsestyrt, (Event Driven
Architecture, EDA) - Ger ett flexibelt sätt att hantera förändringar av
information i system.
» Decentraliserad data-arkitektur - Minskar beroenden till datakälla och
ger därmed en robustare arkitektur.
» Webben som plattform - Internet har under många år i praktiken visat
vara en mycket stabil och kompetent infrastruktur för kommunikation.
Grunden som gjort detta möjligt är ett antal enkla protokoll och principer,
dessa är även en bra plattform för distribuerade system.
•
REST-baserat - Fördelen med REST-baserade tjänster är bland annat enkelheten och
snabbheten.
Arkitektur för Ladok3
Diploma
Ladok3
Students
<core>
Participation
Education
<<Domain Event>>
StudentEtablerad
Results
<generic>
Access
Arkitektur
Administratör
Administratör
Student
Student
Lokal
Lokal portal
portal
Lärosäte
Ladok3
Ladok
användargränssnitt
Ladok kärna
Lokala
anpassningar
Core Services
Studentinformation
Resultat
Studieplan
Utbildningsinformation
Examen
Utbildningsinfo
Studiedeltagande
Infratjänster
Uppföljning
Spårbarhetslogg
Infratjänster
Autentisering
Ladok Integration
CSN
SCB
NyA
Auktorisation
Composite Application
Vad är en tjänst?
• Autonom.
• Publicerar händelser.
Verksamhetstjänst
REST
• Prenumererar på händelser.
• Tjänstegränssnitt
Användargränssnitt
Tjänstegränssnitt
Notifieras
Meddelandehantering
• (Användargränssnitt)
Meddelande
Publicerar
API
• (Distribuerad)
Regler och logik
En komponent som kan finnas.
Komponenten kan delas
med andra tjänster.
Domänmodell
Datalager
REST
Distribuerad komponent
(T.ex. Dokumentlagringssystem)
Meddelandeflöde
Atom
/studiedeltagande
Ny registrering
Resultat
Studiedeltagande
Återbud
Ej påbörjad
Ny
registrering
Återbud
Meddelandeflöde
» Verksamhetsdata
» REST-tjänster och Atom feeds
REST-tjänst
Händelse (Atom feed)
»
»
»
»
»
»
Ge mig student A:s studiedeltagande
Registrera student A på kurstillfälle X
Lämna återbud för student A på kurstillfälle X
Student A har blivit registrerad på kurstillfälle X
Student A har lämnat återbud på kurstillfälle X
Tjänstegränssnitt
Studentinformation
Utbildningsinformation
Studiedeltagande
Resultat
Examen
Uppföljning
Meddelanden
Uppföljning
Examen
Resultat
Stud.delt.
Utb.katalog
Student
Aktiviteter som påverkar respektive tjänst
NyA
Ny utbildning
Student
antagen
•
•
•
•
Dokumenterat
resultat
Student
registrerad
Dokumenterat
bevis för examen
All information har en ägare.
Varje tjänst har den information den behöver för sin funktion.
En tjänst ska inte behöva fråga andra för att få nödvändig information.
Tjänsterna levererar händelser som intressenter kan konsumera och
använda helt eller delvis
Exempel på
händelser/meddelanden
Events
» Händelser på verksamhetsnivå
» Point-to-point
• Producent håller reda på konsumenter
» MoM, Message oriented Middleware
• Köbaserat
» Bus
• Köer och middleware säkerställer att meddelanden kommer fram
» Pull-based, Konsumenter hämtar informationen
• Garanterad leverans
• Ingen lista av prenumeranter
• Ingen middleware
Atom Syndication Format
»
»
»
»
»
rfc 4287, The Atom Syndication Format
XML-baserat document-format
Beskriver listor av relaterad information som “feeds”
Feeds består av ett antal delar, ”entries”
Beskrivs av metadata som kan utökas, vi kan därför
lägga på egen information
» Primära User Stories handlar om listor av webbaserat
innehåll
Feeds
» Publish – Subscribe
• Oberoende av transport.
» Transport med Atom Feeds
• En Feed innehåller 0 – flera entries med events
• Recent Feed
• next-archive, prev-archive
• Feed Consumer
• Event Consumer, oberoende av transport
• Så länge behovet av låg latency saknas är Atom ett kraftfullt
alternativ
Feeds, 2
» En, (1), feed mellan subscriber och publisher
» Publish
• Alla trådar kan publicera
• Alla events i ett EventStore, (DB)
» Subscriber
• En consumer per Feed, även vid flera instanser av en tjänst.
• Events hanteras i tids/sekvens-ordning
• Event Consumer
• ReceivedEvent, PendingEvent, ErrorEvent
• EventHandler
Feeds, 3
Nuvarande Feed
via
Feed
prev-archive
next-archive
Feed
prev-archive
next-archive
Feed
prev-archive
next-archive
Feed
Atom - schematiskt
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title type="text">Events for Ladok3.Utbildningsinformation</title>
<link rel="self" type="application/atom+xml“
href="http://localhost/utbildningsinformation/events/recent"/>
<link rel="via" type="application/atom+xml”
href="http://localhost/utbildningsinformation/events/1,1"/>
<id>urn:uuid:8b562996-75de-4dd7-aac5-0a7e4e491e45</id>
<generator uri="http://localhost/utbildningsinformation/events">
Utbildningsinformation
</generator>
<updated>2013-02-19T08:16:53Z</updated>
<entry>
<title type="text">Event #: 1</title>
<category term="utbildningsinformation.KursTillStatus3Event"/>
<id>e45439da-65d7-40ae-a6b1-27d976a5f529</id>
<updated>2013-02-19T08:16:44Z</updated>
<content type="application/vnd.ladok+xml">
Events / Feeds från Ladok3
» Ladok3 som publicerare?
» Eller varje enskild tjänst?
(måste då hantera events som ej är i kronologisk
ordning)
Att utveckla mot Ladok3
» JVM / Java
• Många alternativ:
o
o
o
o
Spring RestTemplate
Resting
Jersey Client
Restlet
» .NET / C#
• Web.API
» Fiddler
Frågor?
» Böcker
•
•
•
•
REST in Practice
RESTful Web Services
RESTful Web Services Cookbook
REST API Design Rulebook
Frågor?
»?