Als architectuur voor de interface van BoekTrust met derden hebben we gekozen voor een model van Representational State Transfer (REST). Voor meer informatie over REST en de filosofie daarachter, zie de verschillende Restafarian-pages daarover, bv. Wikipedia-entry.

De filosofie achter REST in het algemeen is dat de essentie van een informatiesysteem niet de informatie zelf, maar de bron is. Alle informatie die opgevraagd kan worden (bij ons bv. lijsten van boeken die aan een query voldoen, individuele prijsgegevens van een bepaald boek, etc.), wordt opgevraagd bij een bron - een zgn `resource'. De resource representeert als het ware zijn eigen informatie. De resources dragen vaak de naam van het type informatie dat ze representeren, bv. 'boek' of 'zoekopdracht'.

Er is een standaard set commando's die aan ieder resource gegeven kan worden; wat die commando's precies betekenen is afhankelijk van de resource. De commando's (vgl. CRUD-commando's in traditionele databases) zijn, naar analogie van HTTP-commando's: GET, POST, PUT, DELETE.

De state van een proces wordt niet bijgehouden op de server, we werken zelfs aan een implementatie van stateless security en authenticatie. De client is verantwoordelijk voor het begrijpen in welke state het proces is, en welke mogelijke paden gevolgd kunnen worden naar volgende states. Het is een algemeen karakteristiek van REST dat mogelijke vervolgstates in het antwoord van de server aangegeven worden.

The architecture of the BoekTrust API is modeled after the Representational State Transfer (REST)-model. For more information on REST in general, see the different Restafarian-pages, for example Wikipedia-entry.

The underlying philosophy of REST is that the building blocks of an information retrieval system should be the sources of information communicated, not the information itself. The API is defined as a set of calls to different sources, while the client 'mixes and matches' information as needed for the specific information retrieval task. A source of information is called a resource, and it is named aafter the type of real-world information it provides.

There is a standard list of commands that every resource understands: GET, POST, PUT, DELETE (cf. the CRUD commands for regular database operations). The exact response to any of these commands is specific for the resource; in general, GET is used to retrieve information, PUT is used to create a new object, POST is used to update an already existing object and DELETE is used to delete an object.

The server does not maintain the specific state of a process. It is the client's responsibility to know what state it is in, and what the paths are to possible subsequent states. In most cases, the server's response to a request includes links to all next possible states.

• Example of a transaction to retrieve book data:
  • Voorbeeld-transactie opvragen boekgegevens
• Resources:
  • REST-object book (retrieves a book)
  • REST-object books (retrieves a set of books)
  • REST-object books/nominations (retrieves a set of books that have been nominated for an award)

If you want to retrieve a set of books (rather than a single book), there are two alternative options, depending on the specific goal of the client implementation.

1. use the books object without specification of a result set type (or result set type: full).
2. This will yield a set of ONIX-records.

Example request:

Roelants-iMac:~ rao3$ curl "http://btsoep.appspot.com/rest/search?key1=nur&value1=100-199&flags1=0&limit=20" |xmllint --format -
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 17203    0 17203    0     0  17964      0 --:--:-- --:--:-- --:--:-- 19750

response:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<ONIXMessage xmlns="http://www.editeur.org/onix/2.1/reference">
  <Header>
    <SenderIdentifier>
      <SenderIDType>10</SenderIDType>
      <IDValue>9066342</IDValue>
    </SenderIdentifier>
    <FromCompany>BoekTrust bv</FromCompany>
    <FromEmail>info@boektrust.nl</FromEmail>
    <SentDate>201202160759</SentDate>
    <DefaultLanguageOfText>dut</DefaultLanguageOfText>
    <DefaultCurrencyCode>EUR</DefaultCurrencyCode>
  </Header>
  <Product>
    <RecordReference>978940020786</RecordReference>
    <NotificationType>3</NotificationType>
    <RecordSourceType>4</RecordSourceType>
    <RecordSourceName>BoekTrust Netherlands bv</RecordSourceName>
    <ProductIdentifier>
      <ProductIDType>03</ProductIDType>
      <IDValue>9789400207868</IDValue>
    </ProductIdentifier>
    <ProductForm>BB</ProductForm>
    <Title>
      <TitleType>01</TitleType>
      <TitleText>MTW TIO 7</TitleText>
      <Subtitle>menuleer 1 &amp; 2</Subtitle>
    </Title>
    <Contributor>
      <SequenceNumber>0</SequenceNumber>
      <ContributorRole>A01</ContributorRole>
      <PersonName>J. van Esch</PersonName>
    </Contributor>
    <Contributor>
      <SequenceNumber>1</SequenceNumber>
      <ContributorRole>B01</ContributorRole>
      <PersonName>J. Pen - Vrieswijk</PersonName>
    </Contributor>
    <EditionNumber>1</EditionNumber>
    <Language>
      <LanguageRole>01</LanguageRole>
      <LanguageCode>dut</LanguageCode>
    </Language>
    <Subject>
      <SubjectSchemeIdentifier>32</SubjectSchemeIdentifier>
      <SubjectCode>100</SubjectCode>
    </Subject>
  </Product>
  ...
</ONIXMessage>

This method will be slow for two reasons:

1. Because ONIX is XML (and within the realm of XML documents of a very inefficient kind), the transmission of the data itself will take longer. The response to this query required 17203 bytes.
2. Because books are returned in full detail right away, the corresponding database lookup can be less efficient.

1. use the books object, with specification of result set type: rest.
2. this will yield a set of strings separated by a whitespace; each of these is a full URL to a book resource.

This method will return a result much quicker than method 1:

1. it is lighter on the database
2. it requires much less data for the response: the response to this query took 957 bytes. Method 1 required 17253 bytes, so for this query, method 1 required 18 times as much data as method 2.

however, retrieving actual data of a book will always require at least two HTTP requests, one for the initial scan and one for the actual data.

Example request & response:

Roelants-iMac:~ rao3$ curl "http://btsoep.appspot.com/rest/search?key1=nur&value1=100-199&flags1=0&limit=20&resultSetType=rest" | cat
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   957    0   957    0     0   2850      0 --:--:-- --:--:-- --:--:--  4984
http://btsoep.appspot.com/rest/bookByKey/198506 http://btsoep.appspot.com/rest/bookByKey/197205 http://btsoep.appspot.com/rest/bookByKey/196358 http://btsoep.appspot.com/rest/bookByKey/197060 http://btsoep.appspot.com/rest/bookByKey/193990 http://btsoep.appspot.com/rest/bookByKey/199113 http://btsoep.appspot.com/rest/bookByKey/193989 http://btsoep.appspot.com/rest/bookByKey/193887 http://btsoep.appspot.com/rest/bookByKey/195764 http://btsoep.appspot.com/rest/bookByKey/198197 http://btsoep.appspot.com/rest/bookByKey/197610 http://btsoep.appspot.com/rest/bookByKey/52430 http://btsoep.appspot.com/rest/bookByKey/195911 http://btsoep.appspot.com/rest/bookByKey/190971 http://btsoep.appspot.com/rest/bookByKey/198919 http://btsoep.appspot.com/rest/bookByKey/195260 http://btsoep.appspot.com/rest/bookByKey/197653 http://btsoep.appspot.com/rest/bookByKey/196359 http://btsoep.appspot.com/rest/bookByKey/42012 http://btsoep.appspot.com/rest/bookByKey/194792Roelants-iMac:~ rao3$ 

Use this method in scenario's:

1. to determine the number of results that will be returned
2. when the client implements paging or background loading of results

Note The result of an initial scan should never be cached client-side because the URLs may be transient across multiple lookups of the same data.

Link to deprecated pages.