rest
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| rest [2008/10/23 16:45] – miep | rest [2019/07/18 12:41] (current) – external edit 127.0.0.1 | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | --- // | ||
| + | |||
| + | |||
| + | (scroll down for the English version of the following text) | ||
| + | |||
| + | ====== REST Interface BoekTrust Database ====== | ||
| + | |||
| + | 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. [[http:// | ||
| + | |||
| + | 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' | ||
| + | |||
| + | Er is een standaard set commando' | ||
| + | |||
| + | 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. | ||
| + | |||
| + | |||
| + | ====== REST Interface BoekTrust Database ====== | ||
| + | |||
| + | 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, | ||
| + | |||
| + | The underlying philosophy of REST is that the building blocks of an information retrieval system should be the sources of information communicated, | ||
| + | |||
| + | There is a standard list of commands that every resource understands: | ||
| + | |||
| + | The server does not maintain the specific state of a process. It is the client' | ||
| + | |||
| + | * 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/ | ||
| + | |||
| + | ===== Retrieving a set of books ==== | ||
| + | |||
| + | 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. | ||
| + | |||
| + | ==== Method 1: direct retrieve (default) | ||
| + | - use the [[books]] object without specification of a result set type (or result set type: '' | ||
| + | - This will yield a set of ONIX-records. | ||
| + | |||
| + | Example request: | ||
| + | < | ||
| + | Roelants-iMac: | ||
| + | % Total % Received % Xferd Average Speed | ||
| + | | ||
| + | 100 17203 0 17203 0 | ||
| + | </ | ||
| + | |||
| + | response: | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | ... | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | This method will be slow for two reasons: | ||
| + | - 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. | ||
| + | - Because books are returned in full detail right away, the corresponding database lookup can be less efficient. | ||
| + | |||
| + | ==== Method 2: using REST paths ==== | ||
| + | - use the [[books]] object, with specification of result set type: '' | ||
| + | - 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: | ||
| + | - it is lighter on the database | ||
| + | - 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: | ||
| + | % Total % Received % Xferd Average Speed | ||
| + | | ||
| + | 100 | ||
| + | http:// | ||
| + | </ | ||
| + | |||
| + | Use this method in scenario' | ||
| + | - to determine the number of results that will be returned | ||
| + | - 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. | ||
| + | |||
| + | |||
| + | |||
| + | ===== Other === | ||
| + | Link to [[deprecated: | ||
| + | |||
| + | |||