BelBoek / BoekTrust documentatie

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
 --- //[[miep@belboek.com|Roelant Ossewaarde]] 2008/05/05 16:07// De links op deze pagina zijn verouderd en werken niet. Up-to-date informatie is te vinden door te klikken op de REST-objecten op de pagina ''[[REST]]''.

====== Voorbeeld-transactie opvragen boekgegevens ======



Er zijn twee simplificaties aangebracht om de voorbeeld-transactie helder te houden:
  - authenticatie vindt niet plaats; in werkelijkheid zal dat wel gebeuren, op basis van HTTP BASIC authenticatie of mbv. cookies / authid's. 
  - alle URI's worden niet 'vertaald' zoals dat hoort volgens de RFC's; daardoor zijn de query-strings leesbaarder. Maw., een query als "?query=titel%3Dauteur" wordt op deze pagina opgeschreven als ?query=titel=auteur.


== Stap 1: Client → Server: Request query voor boek 'Aanslag' van 'Mulisch' ==

De client stuurt via HTTP aan resource ''[[booklist]]'' de GET-request:

<code>
GET http://www.boektrust.nl/booklist?authid=623AGJHL23&query=auteur=^MULISCH&filter=titel=.*AANSLAG.*
</code>

Van belang zijn elementen ''query'', ''filter'' : deze twee elementen samen vormen de query waarmee gezocht wordt in de indexen van de database. Meer informatie over de opzet van de database en de mogelijkheden van de query-taal zijn te vinden op pagina [[Database en Queries]]. Van belang hier is dat er een key=value paar wordt doorgegeven, waarvan de value een regular expression is. In dit geval wordt gezocht naar alle boeken waarvan:
      * ''auteur begint met MULISCH'', en bovendien
      * ''titel bevat AANSLAG''.


== Stap 2: Server → Client: Response query voor boek ==

De server stuurt response:

<code xml>
200 OK
<?xml version="1.0"?>
<bt:booklist xmlns:bt="http://www.boektrust.nl/" xmlns:xlink="http://www.w3.org/1999/xlink">
  <bt:NumberOfBooks>3</bt:NumberOfBooks>
  <bt:Book bt:recordreference="978906262331" xlink:href="http://www.boektrust.nl/book/978906262331?detail=basic"/>
  <bt:Book bt:recordreference="978906262123" xlink:href="http://www.boektrust.nl/book/978906262123?detail=basic"/>
  <bt:Book bt:recordreference="978906262220" xlink:href="http://www.boektrust.nl/book/978906262220?detail=basic"/>
</bt:booklist>
</code>


De response die de server stuurt is een standaard HTTP-response. Bij foutmeldingen wordt een standaard HTTP-code teruggestuurd (bv. error 403 - Permission denied, als iemand niet geauthenticeerd is). In dit geval wordt status 200 teruggegeven, en een lijst met resources die aan de zoekopdracht voldoet.

== Stap 3: Client → Server: Request detail voor boek 978906262331==

De client stuurt via HTTP aan resource ''[[book]]'' de GET-request:

<code>
GET "http://www.boektrust.nl/book/978906262331?detail=basic"
</code>


NB: de precieze lokatie (de URI http://www.boektrust.nl/book/978906262331?detail=basic) is niet vooraf gedefinieerd; BoekTrust kan dat altijd nog wijzigen. Wat wel is gedefinieerd is dat de lokatie van basis-detail-gegevens van book altijd kan worden opgevraagd via een query naar resource ''booklist''. Zo implementeren wij //loose coupling// van componenten. 

== Stap 4: Server → Client: Response query voor boek ==

De server stuurt naar de client response:

<code>
200 OK
</code>

<code xml>
<?xml version="1.0"?>
<bt:book xmlns:bt="http://www.boektrust.nl/" xmlns:xlink="http://www.w3.org/1999/xlink">
  <bt:Book>
    <boek versie="0.9">
    <isbn>906262331X</isbn>
    <ean>9789062623310</ean>
    <auteur>Harry Mulisch</auteur>
    <titel>De Aanslag</titel>
    </boek>
    <bt:additional><bt:Book bt:recordreference="978906262331" bt:type="flaptekst" xlink:href="http://www.boektrust.nl/book/978906262331?detail=flaptekst"/></bt:additional>
  </bt:Book>
</bt:booklist>
</code>

Van belang is dat de server niet ALLE informatie over het boek verstuurt, maar slechts een deelverzameling van basisgegevens. Verdere gegevens moeten opnieuw opgevraagd worden; in dit voorbeeld worden flaptekst-gegevens nog niet vermeld, maar moeten die apart worden opgevraagd via de gegeven link. De client mag er van uitgaan dat alle informatie die de resource ''[[book]]'' heeft over een boek wordt weergegeven, hetzij door middel van de informatie zelf (in dit voorbeeld: isbn, ean, auteur, titel), hetzij door middel van een link naar andere informatie.