Koha Web Services Overview

• Use cookie-based session
• biblios gets username and password
• sends to Koha for auth decision
• Koha sends back yea/nay + cookie
• session cookie is used for future transactions
• also returns some information about validation of MARC records saved in Koha

o view-only fields

        o record ID field
        o for biblioitems.itemtype, list of fields, subfields, and valid values that must be set by cataloger according to a set list of values/

• Save either to DB or to reservoir
• Reponse to save API can include

o failure – MARC XML invalid

        o conditional failure -- MARC has following cataloging errors -- a list is returned so that biblios can highlight the appropriate fields
        o there should be an option to do a force save of record that has non-fatal conditional failure warnings
        o OK -- MARC XML returned, possibily with changes  for things like the record ID
  * For embedded item and biblioitem data, Koha will either not send it back to biblios or will mark it as view-only.  With the except of bibliioitems.itemtype for new records, Koha will recreate embedded fields for item information from the items table.

• MARC XML stored in Zebra is not guaranteed to be completely up-to-date
• This means that when user selects bib from Koha target to edit, a call has to be made to a separate API to see if the record is dirty, and if so, return the current version.

API structure

• XML over HTTP API
• Following APIs

o Authenticate

              + Input
                    # Username
                    # Password
              + Invoke POST http://koha-base/cgi-bin/koha/svc/authentication with parameters 'userid' and 'password' as URL encoded form parameters -- (for testing purposes, use userid 'api' and password 'api').
              + Response
                    # HTTP request status = 200 in a all cases
                    # If authentication succeeded, cookie with name 'CGISESSID'
                    # XML output containing status in response.status element; value can be one of
                          * maintenance == Koha is down for maintenance
                          * failed == supplied credentials in correct, or user does not have the relevant Koha privilege
                          * ok == authentication OK
                          * expired == session cookie has expired; resubmit credentials to get a new session cookie
        o BibProfile
              + Requirements
                    # Valid session cookie
              + Input
                    # None
              + Invoke GET http://koha-base/cgi-bin/koha/svc/bib_profile
              + Output -- XML containing
                    # MARC tags to set view-only
                    # Tag and subfield containing ILS record ID
                    # List of tags and subfields containing values that must be set from a list (e.g., biblioitems.itemtype) -- see the special_entry element in the example below
                    # List of authorised values

<?xml version='1.0' standalone='yes'?> <response>

<auth_status>ok</auth_status>
<bib_number>
  <subfield>c</subfield>
  <tag>999</tag>
</bib_number>
<mandatory_subfields>
  <subfield>
    <subfield_label>c</subfield_label>
    <tag>040</tag>
  </subfield>
  <subfield>
    <subfield_label>a</subfield_label>
    <tag>245</tag>
  </subfield>
  <subfield>
    <subfield_label>c</subfield_label>
    <tag>942</tag>
  </subfield>
  <subfield>
    <subfield_label>a</subfield_label>
    <tag>300</tag>
  </subfield>
</mandatory_subfields>
<mandatory_tags>
  <tag>000</tag>
  <tag>003</tag>
  <tag>005</tag>
  <tag>008</tag>
  <tag>040</tag>
  <tag>245</tag>
  <tag>300</tag>
</mandatory_tags>
<reserved_tags>
  <tag>999</tag>
  <tag>942</tag>
  <tag>952</tag>
</reserved_tags>
<special_entry>
  <field>
    <subfield>c</subfield>
    <tag>942</tag>
  </field>
  <valid_values>
    <value>
      <code>AR</code>
      <description>Models</description>
    </value>
    <value>
      <code>BKS</code>
      <description>Books, Booklets, Workbooks</description>
    </value>
    <value>
      <code>CF</code>
      <description>CD-ROMs, DVD-ROMs, General Online Resources</description>
    </value>
    <value>
      <code>IR</code>
      <description>Binders</description>
    </value>
    <value>
      <code>KT</code>
      <description>Kits</description>
    </value>
    <value>
      <code>SER</code>
      <description>Serials</description>
    </value>
    <value>
      <code>SR</code>
      <description>Audio Cassettes, CDs</description>
    </value>
    <value>
      <code>VR</code>
      <description>DVDs, VHS</description>
    </value>
  </valid_values>
</special_entry>

</response>

        o RetrieveBib
              + Requirements
                    # Valid session cookie
              + Input
                    # biblionumber
              + Invoke GET http://koha-base/cgi-bin/koha/svc/bib/biblionumber
              + Reponse
                    # HTTP response status 400 if invalid biblionumber
                    # HTTP response status 401 or 403 if not authorized (not implemented yet)
                    # HTTP response status 200 and XML record following MARC21 slim schema.
        o ValidateBib -- do later
        o SaveBib
              + Requirements
                    # Valid session cookie
              + Input
                    # MARC XML
                    # biblionumber (if supplied, this is a record replace; if not supplied, this is a new record)
                    # Override conditional failure
              + Invoke    POST http://koha-base/cgi-bin/koha/svc/bib/biblionumber for replace
              + Invoke POST http://koha-base/cgi-bin/koha/svc/new_bib for new record
              + Output -- XML response including
                    # Status = "ok" | "failed"
                    # resulting biblionumber
                    # Failure message if applicable
                    # resulting MARC XML record enclose in a MARCXML element
                    # Conditional failure message (this will be a structure that includes info about specific tags, subfields, and so on) -- not yet implemented

• Can biblios guarantee that MARC XML it pushes is in UTF-8 (or less ideal, MARC-8)
• If records are pushed in UTF-8 in every case, biblios should make sure that the Leader/09 (for MARC21) is set to 'a'.