Supporting the ‡biblios 'send' web service API in your application

‡biblios can use a simple web service API to retrieve and save MARC bib records in another application such as an ILS. The Koha ILS has an implementation of this API, but it should be simple to port to another application.

Four services are defined:

  • authentication — authenticate user to the ILS and return a session cookie
  • bib_profile — return some information what the target ILS expects in new or edited bib records, including mandatory tags, mandatory subfields, and reserved tags
  • bib — retrieve or update a bib record
  • new_bib — store a new bib record

authentication

‡biblios will POST to http://host/path/to/service/authentication two form-encoded parameters, userid and password. The service should return XML signaling whether the credentials identify a user who is allow to retrieve and save bib records:

<?xml version='1.0' standalone='yes'?>
<response>
  <status>ok</status>
</response>

If the status is "ok", the service should also return a session cookie that ‡biblios will submit when calling the other services.

The statuses understood by ‡biblios are

  • ok — user is authorized
  • failed — credentials are not correct; ‡biblios will allow user to resubmit the userid and password.
  • maintenance — the target application is not accepting logins at the moment
  • expired — the session cookie has expired; ‡biblios will resubmit the login

bib_profile

After authenticating to the target, ‡biblios will GET http://host/path/to/service/bib_profile to find out what the target application expects of bib records that are saved or created for it. The service should return an XML response like this:

<?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>a</subfield_label>
      <tag>245</tag>
    </subfield>
  </mandatory_subfields>
  <mandatory_tags>
    <tag>008</tag>
  </mandatory_tags>
  <reserved_tags>
    <tag>999</tag>
    <tag>942</tag>
  </reserved_tags>
  <special_entry>
    <field>
      <subfield>c</subfield>
      <tag>942</tag>
    </field>
    <valid_values>
      <value>
        <code>BK</code>
        <description>Books</description>
      </value>
      <value>
        <code>CF</code>
        <description>Computer Files</description>
      </value>
    </valid_values>
  </special_entry>
</response>

The auth_status element contains the user authentication status; see the list of statuses for the authentication service.

bib_number tells ‡biblios where to find the bib identifier assigned by the target application, while mandatory_tags and mandatory_subfields specify fields that the target application requires in order to accept a new or updated bib. reserved_tags is the list of MARC tags that the target requests that ‡biblios not permit the cataloger to edit directly.

special_entry specifies, for the specified tag and subfield, a list of valid values for that subfield. ‡biblios will use a drop-down list to manage data entry for that subfield.

bib

‡biblios will GET http://host/path/to/service/bib/bib_identifier to retrieve a bib record from the target. If the record is available, the service should return it in MARCXML format using the MARC21slim schema:

<?xml version="1.0" encoding="UTF-8"?>
<record
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.loc.gov/MARC21/slim 
      http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"
    xmlns="http://www.loc.gov/MARC21/slim">

  <leader>00461nam a22001817a 4500</leader>
  <controlfield tag="008">070128t        xxu||||| |||| 00| 0 eng d</controlfield>
  <datafield tag="245" ind1=" " ind2=" ">
    <subfield code="a">The war of the cats and dogs.</subfield>
  </datafield>
  <datafield tag="999" ind1=" " ind2=" ">
    <subfield code="c">1</subfield>
    <subfield code="d">1</subfield>
  </datafield>
</record>

If the bib does not exist, the service should return HTTP status 404. If the user does not have permission to retrieve the bib, the service should 403 and return an auth_status response.

To update an existing bib, ‡biblios will POST the MARCXML bib record. The service should 404 if the bib does not already exist and 403 if the user is not authenticated. Upon a successful reponse, the service should return an XML response like this:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <biblionumber>134</biblionumber>
  <marcxml>
    <!-- record in MARC XML format; note that
         target can make changes to the record,
         which ‡biblios will use to refresh its
         version of the record.
     -->
  </marcxml>
</response>

If the target could not update the record, it should set status to "failed" and return a human-readable explanation of the error in an error element.

new_bib

‡biblios will POST to http://host/path/to/service/new_bib to save a new bib record in the target. The service should use the same response format used by a POST to bib.