The library's API

The Koldo Mitxelena library makes the information in its catalog available through a REST-style API (Application Programming Interface), so you can use it and integrate it into your own site. This document describes the functionality exposed by the API, and is meant as a guide for bloggers, webmasters or programmers who might use these access tools to enrich web sites and use the information in the library catalog in useful and creative ways.

The term book is used in this document to mean "resource listed in the catalog", it could be a real book, a CD, a poster, a photograph, or any othe the objects, physical or digital, that a library might hold.

Contents

Accessing a Book Record in the Catalog
Search
Returned Records
HTTP Status Codes

Accessing a Book Record in the Catalog

Get the record for a book:

URL: http://liburutegia.gipuzkoa.net/api/rest/1.0/book/reference.xml

HTTP method: GET

Result: Record for the book, in Dublin Core format.

XML Example

 curl http://liburutegia.gipuzkoa.net/api/rest/1.0/book/000000594191.xml

<?xml version="1.0" encoding="utf-8" ?>
<book xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:identifier>(KM)AMICUS:000000594191</dc:identifier>
    <dc:identifier>ISBN:978-84-8152-360-7</dc:identifier>
    <dc:identifier>CDU:913 ESP</dc:identifier>
    <dc:title>Guía oficial de campings de España</dc:title>
    <dc:description>Tít. tomado de la cub
    Índices
    </dc:description>
    <dc:type>book</dc:type>
    <dc:coverage type="spatial">España</dc:coverage>
    <dc:language>eng</dc:language>
    <dc:language>eng</dc:language>
    <dc:language>fre</dc:language>
    <dc:language>ger</dc:language>
    <dc:format>526 p., [2] p. de mapas mapas 24 cm +</dc:format>
    <dc:publisher>[Madrid]. Turespaña</dc:publisher>
    <library_urls>
          <url name="Koldo Mitxelena">
              <![CDATA[
                  http://www4.gipuzkoa.net/KMKatalogoa/default.aspx?hreciid=|library%2Fmarc%2Famicus|000000594191
              ]]>
        </url>
    </library_urls>
    <dc:rights></dc:rights>
    <dc:source></dc:source>
    <dc:date>2009</dc:date>
    <dc:relation type="marc:777">Guía oficial de campings de España. (KM)594192</dc:relation>
    <dc:relation type="marc:777">Mapa de campings y carreteras de España]. (KM)594533</dc:relation>
    <dc:subject type="marc:650">Camping</dc:subject>
</book>

Search

Returns the list of records in the catalog that match the search criteria specified.

URL: http://liburutegia.gipuzkoa.net/api/rest/1.0/books.format where format is one of xml, rss, js, json, html.

HTTP method: GET

Parameters:

q: Optional. Text query parameter.
Example: http://liburutegia.gipuzkoa.net/api/rest/1.0/books.xml?q=fundacion
author: Optional. Name of the author.
title: Optional. Title of the book.
isbn: Optional. ISBN for the book
keywords: Optional. Subject matter of the book.
Example: http://liburutegia.gipuzkoa.net/api/rest/1.0/books.xml?keywords=beasain

Result: A list of the records found in the catalog.

XML Example

 curl "http://liburutegia.gipuzkoa.net/api/rest/1.0/books.xml?q=fundacion"

<?xml version="1.0" encoding="utf-8" ?>
<books>
    <book>
        <reference>000000432888</reference>
        <title>Aena</title>
        <subtitle>Arte garaikideko bilduma : [Artearen Kutxaguneko Kubo Aretoan] = Colección de arte contemporáneo : [Sala Kubo-Kutxaespacio del Arte]</subtitle>
        <authors>
            <author>Fundación Kutxa</author>
        </authors>
        <summary>Textos en euskera, castellano, francés e inglés</summary>
        <cdu>7</cdu>
        <year>2002</year>
        <series>Colección Kubo-Kutxa ;</series>
        <subject>
            <keyword>arte</keyword>
            <keyword>exposiciones</keyword>
            <keyword>fundación aena</keyword>
            <keyword>s. xx</keyword>
            <keyword>colecciones de arte</keyword>
            <keyword>exposiciones</keyword>
        </subject>

        <terms_found>
            <keyword score="4">fundación</keyword>
        </terms_found>
    </book>
</books>

Returned Records

Record listing

A list or array filled with objects with the following attributes:

reference: Identifier for the book
- In the example: 000000432888
title
- In the example: Aena
subtitle
- In the example: Arte garaikideko bilduma : [Artearen Kutxaguneko Kubo Aretoan] = Colección de arte contemporáneo : [Sala Kubo-Kutxaespacio del Arte]
authors
- In the example: Fundación Kutxa
summary: A summary or description of the book.
- In the example: Textos en euskera, castellano, francés e inglés
CDU: Library call number for the book.
- In the example: 7.036 FUN AEN
year: Publication year.
- In the example: 2002
series: Series to which the book belongs.
- In the example: Colección Kubo-Kutxa
subject: Keyword list for the subject matter of the book.
- In the example: arte, exposiciones, fundación aena,s. xx, colecciones de arte, exposiciones
terms_found: Listing of the search terms that matched.
- In the example: fundación (4 matches in the record)

HTTP Status Codes

The API is designed to return the appropriate HTTP status code for the requests it receives.

200 OK : The request was processed successfully.
404 Not Found : No matching book was found.
500 Internal Server Error : An internal error has occurred within the software that implements the API. Please let us know the context in which you encounter this (if ever!), so we can investigate.
503 Service Unavailable : Our servers cannot handle your request at this time (downtime, overload, etc.).

Examples

The following examples illustrate the use of the API: