MWeb Documentation - MWeb Enterprise -- planning* -- online exhibits -- periods* -- administration* -- templates* -- PPS -- Flash - MWeb Universal - Glossary - Interface Admin - Messages - Support

MWeb™ XML Server


Welcome to MWeb™!

This document pertains to MWeb Enterprise only.

Contents


General Guidelines

Purpose

The MWeb XML Server (MXS) is a Web Service that generates XML from an MWeb Enterprise Database for nearly all requests that the MWeb frontend can handle. This enables you to develop your own interface to an MWeb Enterprise Database, using HTML, DHTML, ASP, Flash, or any other technology. This document explains how to use MXS.

MWeb Enterprise is one of a family of MWeb products. It uses a proprietary database structure. The Database may be in one of several database systems, such as SQL Server, MySQL, Oracle, DB2, or Foxpro. An MWeb Enterprise Database is a read-only database, optimized for searching; it is rebuilt periodically by the site to add new information.

MXS works only with MWeb Enterprise, not with databases used by MWeb Universal.

MWeb Enterprise architecture

Requests

Your application may be HTML pages, ASP pages, Flash movies, or anything else. MXS can work with your application in two ways:

  1. REQUEST/RESPONSE METHOD -- Your application sends a "request" to MXS and receives a "response" in XML format. For example, your application may have a way for the user to enter search terms and send them to MXS; MXS would send back the appropriate Search Results. Another scenario is when your application wishes to send a followup request, such as a Full-Record request for a record previously retrieved as a brief record in response to a search. Requests are HTML GET queries, using the syntax shown in the remainder of this document. Responses are also described below.

  2. RESPONSE-ONLY METHOD -- Alternatively, your users can use the search interface in MWeb Enterprise to build a set of records (called Favorites) that they want to send to your XML application. Then they click a button in MWeb to send the Favorites in XML to your application. (In this document we refer to the results as a "response", even though it is not the result of a request from your application.)

Use of the Response-Only method must be coordinated with Systems Planning.

All MWeb requests are case-insensitive, including fieldnames and data values in requests. Therefore these two requests have identical results:

http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;Title=Tokyo Road;Start_Date=1800;End_Date=1880
http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;title=tokyo road;start_date=1800;end_date=1880

Responses

Responses may or may not be formatted into lines. In other words, the response may be like this, not as shown in the examples below (which are formatted for readability).

<?xml version="1.0" encoding="ISO-8859-1" ?><record><Artist>Toyohara Kunichika, Japan, 1835-1900</Artist><Artist>Utagawa Kunisada (Toyokuni III), Japan, 1786-1864</Artist><Title><i>The Sixth Month</i></Title><Series>Scenes of the Twelve Months: Water, Plum, and Moon</Series><Date>circa 1854</Date><Medium_&_Technique>Triptych; color woodblock prints</Medium_&_Technique><Dimensions>Overall: Image: 14 3/16 x 29 in. (36.0 x 75.4 cm); Paper: 14 3/16 x 29 7/16 in. (36.0 x 75.4 cm)</Dimensions><Museum_Number>M.82.150.34a-c</Museum_Number><Classification_Term>Print</Classification_Term><Credit_Line>Gift of Lyle and Marie Fair</Credit_Line><Department>Japanese Art</Department><Place>Japan</Place></record>

In an MWeb Enterprise Database, data elements that are links to other records are stored as HTML links. For example, a record for an artwork will have the artist's name as an HTML link so the user can click to view the artist record. Your application may either display these as clickable links, if appropriate, or strip the link tags and display just the link text. For the former, convert &#60; to <, &#62; to >, &#34; to ", and &#39; to '. For the latter, remove everything between the &#60; and &#62; pairs.

Fields are identified by the terms and in the letter case specified by the site, except that spaces are replaced by underbars, ampersands are replaced by "and", and number signs (#) are replaced by "Number". For example, if the site uses the fieldname "Medium & Technique", the XML element name will be "Medium_and_Technique". Of course your program may edit the fieldnames for display purposes.

Character encoding

All responses are encoded in UTF-8, the international standard (see The Unicode Consortium). UTF-8 will display correctly in modern browsers (although the user's computer must have a font with the characters being viewed).

Limits to Number of Hits Returned

If a search finds more than 10,000 records ("hits"), only the count is returned. Your application should check the count attribute of the top-level element and advise the user to perform a more focused search. This limit exists because a large number of hits is not very useful, and only burdens the server.

In addition, there is a system limit on the number of records for which brief data is returned; this is the Groupsize (see Glossary), currently 12. The remainder are returned as Placeholder Records (see next subsection). To override this limit, use the URL parameter number. For example, here is a Keyword Search in which 20 brief records are requested:

     http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=badge;number=20

Discretion is urged in using a high number, since it will affect response time for the request, as well as degrading server performance for all users.

You must also use the number parameter when using the results request to get additional Search Results:

     http://www.example.org/mwebcgi/mwebxml.exe?request=results;keys=1|2|3|4|5|6|7|8|9|10|11|12|13|14|15;number=20

Without the number you will get only 12 brief records, even if you send more than 12 keys. The number can be higher than the number of keys sent, if you wish, as in the example above.

Placeholder Records

Placeholder Records are record tags with the MWeb Key attribute, and follow immediately after the brief records. (The top-level tag is not shown in this example.)

     <record key="134514" id="6865" type="902">
       <image>
	  <thumbnail>
            http://www.lacma.org/art/images/exhibitions/th-scupeuro.jpg
          </thumbnail>
       </image>
       <Exhibition>
          <a href='?request=exhibit;id=6865'>European Sculpture since 1950</a>
       </Exhibition>
       <Department>European Sculpture</Department>
       <Dates>March 25, 2005 - May 13, 2006</Dates>
       <Location>Main Building, 5th Floor</Location>
       <Description>Online exhibition 2005</Description>
     </record>

     ... [additional brief records]

     <record key="134515"/>
     <record key="134523"/>
     <record key="134528"/>
     <record key="134506"/>
     <record key="134512"/>
     ...

Scenarios

A typical scenario would be for a user to perform a search to find records of interest, then view these records. Such an interaction would proceed like this for a Keyword Search:

  1. Your application displays a form or list for the user to enter or select words describing the topic of interest.
  2. Your application forms the words into a Keyword Search request and sends it to MXS.
  3. MXS returns the Search Results response, which includes the number of records found and their Keys. Your application should store this list of Keys while the user pages through them. In addition, brief data for the first Group of records are returned. Each brief record includes the record's Key, ID, and Type attributes (described below).
  4. Your application displays the brief records for the first group of hits. If there are more hits than the Groupsize, your application should display a way for the user to page through them, using "Previous" and "Next" buttons, a list of page numbers, or some similar method.
  5. If the user requests another page of hits, your application sends a request to MXS for the additional brief records.
  6. Your application displays the brief data for each record with a means for the user to view the Full Record (link or button).
  7. When the user selects a record, your application forms the Key into a Full Record request and sends it to the XML Server.
  8. MXS returns a Full Record for your application to display.

The purpose of this approach is to avoid transmission of large amounts of data from searches. For example, if there were 5,000 hits from a search, your Application probably couldn't make use of that many brief records. However the first group of brief records are sent in order to save a server call.

Keys, IDs, and Types

MWeb maintains two identifiers for each record in the database. Keys are generated by MWeb and are unique across the MWeb Enterprise Database. They are 32-bit positive integers in the range 1 to 2,147,483,648. Keys have no intrinsic meaning at all.

Unfortunately, MWeb Keys are reassigned whenever the MWeb Database is rebuilt from the client's production databases. Therefore MWeb also maintains the client's own IDs. These are alphanumeric strings that are stored almost exactly as received from the client*; we make no claims as to their uniqueness or stability, but they tend to have both these characteristics. Generally these are 36 characters or shorter, but may be any length.

* The following symbols are removed from clients' IDs as they cause trouble in URLs: '&;#

In most museum collection-management systems the IDs are not unique throughout the system but only within a record-type. Thus MWeb also assigns to each record a Content Type (usually just called the Type). The combination of the ID and Content Type is the best way to be able to retrieve a record in the future. When you display a Full Record in your application, the URL should use the ID and Type in case the user wants to save the URL as a bookmark.

Please see the MWeb Glossary for help with other terms. Terms with special meanings in MWeb are shown capitalized in this document; the Glossary defines each one.

Subsets and Content Types

As discussed in the previous section, MWeb's most basic categorizing of records is by Content Type. However, these are not used in searching. Instead, a slightly broader concept called Subsets is the finest category of records that is retrievable.

For example, a museum might have artwork records in the Permanent Collection Content Type, and other artwork records in the Temporary Loans Content Type. Assume that both these Content Types are in the Artwork Subset. In that case, your application may request to retrieve records belonging to the Artwork Subset, but may not request to retrieve records of a specific Content Type.

To specify a Subset in a search, add the subset parameter as shown in the examples below.

To retrieve lists of Content Types and Subsets from the database, see the Content Types and Subsets requests.

Display Types (dtype parameter)

Besides retrieving all records matching the search criteria, MWeb can also retrieve only those records matching the search criteria that also have images. MWeb refers to these two variations as the Display Type.

Display Type d is the default ("d" stands for "data"). A search URL with no dtype parameter, or with the parameter dtype=d will retrieve all records matching the search criteria. If the search URL includes the parameter dtype=i, only records matching the search criteria that also have images are retrieved.


Search Requests & Responses

For clarity, the URLs shown below for requests do not include the Caller parameter, an MXS security measure. Please see Security and Privacy for details.

Keyword Search

Requests MXS to perform a Keyword Search and return the Search Results.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy;dtype=d

Form 3
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy;dtype=i

Form 4
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy yyy2

Form 5
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword="yyy yyy2"

Form 6
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy or yyy2

Form 7
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy;subset=zzz

Form 8
http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=yyy;subset=zzz;subset=zzz2
Usage Use Form 1 or 2 to retrieve all records, whether or not they have images. They perform identically.

Use Form 3 to retrieve only records with images.

Use Form 4 to search for more than one keyword (boolean AND).

Use Form 5 to search for a phrase.

Use Form 6 for a boolean OR search.

Use Form 7 to restrict the search to a specific Subset.

Use Form 8 to restrict the search to more than one Subset.

Change "www.example.org" to the site's URL.

Change yyy to the keywords to be searched. Do not use quotation marks around them. You may use multiple keywords, also without quotation marks. Each additional keyword slows down the search.

Enclose the set of keywords in double quotation marks to search them as a phrase.

Change zzz to the Subsets to be searched. You may first need to find the list of Subsets used in the database.
Response
<searchresults count="179">
  <subset db="1" id="100" name="Artworks">
    <record key="4544" id="73085" type="101">
      <image>
        <descriptor>back view</descriptor>
        <copyright>Copyright 1988</copyright>
        <thumbnail>http://www.example.org/mwebimages/cat01_001/thumb/M85_77_4.jpg</thumbnail>
        <fullimage>http://www.example.org/mwebimages/cat01_001/full/M85_77_4.jpg</fullimage>
      </image>
      <Title>The Sixth Month</Title>
      <Artist><a href="/mwebcgi/mwebxml.exe?request=record;id=61212;type=701">
                      Toyohara Kunichika</a></Artist>
      <Country>Japan</Country>
      <Date>1900</Date>
      <Medium>ink on silk</Medium>
    </record>

    ... 11 more brief records ...

    <record key="3322">
    </record>
    <record key="5120">
    </record>
  </subset>
  <subset db="1" id="200" name="Library">
    <record key="7964">
    </record>
    <record key="2469">
    </record>

    ... more placeholder records ...

  </subset>
</searchresults>
Remarks The first record shown above is a typical brief record; the first Groupsize hits are returned like that (see additional notes under Search Results below). The remainder of the hits are returned as Placeholder Records.

If more than 10,000 records are found by the search, only the top-level element is returned, as in this example (see Planned Enhancements):
<searchresults count="13551">
</searchresults>
For each brief record, three attributes are provided: key is the MWeb unique identifier; it is the fastest way to retrieve a record and is required to retrieve additional brief records (see next section), but the number may change whenever the MWeb database is rebuilt. id and type are the permanent identifiers for the record provided by the site; these should be stable over time.

The id and name attributes of the subset element indicates which Subset the records come from. id is the permanent identifier (a 3-digit number) and the name is suitable for display.

The db attribute is always "1" for an MWeb Enterprise Database.

Records are returned in the default sort order specified by the site.

Fields are returned in the order specified by the site. Except for image fields, the element names reflect the site's preference of case.

Links in the MWeb Enterprise Database to other records are passed through, for example in the Artist tag in the example. This allows you to make these into links to the other Full Record if you wish to. The parameters in the link use the permanent identifiers provided by the site, so they should be stable over time.

Search Results

Requests MXS to return brief data for a list of Keys. Only a few fields per record are returned, those that the site has determined are required to construct a brief-record display; and only the first image for each object. You may request Full Records for these by sending additional requests. The response includes the information needed to do so.

Regardless of how many keys you add to the request, only 12 brief records are returned unless you use the number parameter.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=results;keys=111|222|333
Usage Change "www.example.org" to the site's URL.

Use the MWeb numeric Keys in the keys parameter.

Separate keys by a vertical bar.
Response
<searchresults count="179">
  <subset db="1" id="100" name="Artworks">
    <record key="4544" id="73085" type="101">

    ... Internal structure is the same as for the first record of the 
                         response under Keyword Search above ...

    </record>

    ... one record for each key you send ...

  </subset>
</searchresults>
Remarks The specific data fields returned and their names depend on the site's preferences.

The records may be in more than one table, as shown in the response under Keyword Search above.

Advanced Search

Advanced Searching requires two request/response sequences, one to find out what fields are searchable, the other to request the search.

1. Request the Search Categories

MWeb does not support searching of specific fields. Instead, similar fields are grouped into Search Categories; this is the same approach as the Dublin Core. For example, all titles may be in the Title Search Category, and all personal names in the Persons Search Category.

Search Categories are different for each MWeb site, and are designed to support the needs of the site's clientele. Therefore the first step in an Advanced Search is to request MXS to return a list of Search Categories that are available for advanced searching.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=searchcats

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=searchcats;subset=0

Form 3
http://www.example.org/mwebcgi/mwebxml.exe?request=searchcats;subset=yyy
Usage Use Form 1 or 2 to request the Search Categories for the entire Database

Use Form 3 to request the Search Catagories that apply to a single Subset

Change "www.example.org" to the site's URL.

Change yyy to the desired Subset
Response
<searchcats subset="0" count="6">
  <searchcat>
    <type>text</type>
    <code>_t1101</code>
    <name>Titles</name>
  </searchcat>
  <searchcat>
    <type>text</type>
    <code>_t1102</code>
    <name>Artists/Authors/Creators</name>
  </searchcat>
  <searchcat>
    <type>text</type>
    <code>_t1104</code>
    <name>Subjects (includes artist names)</name>
  </searchcat>
  <searchcat>
    <type>text</type>
    <code>_t1109</code>
    <name>Description/Contents</name>
  </searchcat>
  <searchcat>
    <type>startdate</type>
    <code>_>1091</code>
    <name>From</name>
  </searchcat>
  <searchcat>
    <type>enddate</type>
    <code>_<1092</code>
    <name>To</name>
  </searchcat>
</searchcats>
Remarks

The subset in the <searchcats> element is the Subset whose Search Categories were requested (the yyy in the example). Unless it is zero, this needs to be added to the search request, as shown in the next section.

The types help you present the Search Categories to the user:

  • text means the user may enter either one or more keywords and/or phrases
  • startdate means the user may enter the start-date of a date range by which to limit the search
  • enddate means the user may enter the end-date of a date range by which to limit the search

The codes are the parameter names to include in the URL of the Advanced Search (see next section).

The names are the names used by the site to display to their users.

The Search Categories are returned in the order recommended for display to the user.

See the MWeb Help file for the syntax of the user entry to the Search Categories.

2. Perform the Advanced Search

Request MXS to perform an Advanced Search and return the search results. Use the Search Category codes as parameter names in the URL. Note that codes begin with an underscore.

Only a few fields per record are returned, those that the site has determined are required to construct a brief-record display; and only the first image for each object. You may request full records for these by sending additional requests. The response includes the information needed to do so.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;_t1101=tokyo road

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;_t1101="tokyo road"

Form 3
http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;_t1101=tokyo road;_>1091=1800;_<1092=1880

Form 4
http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;_t1101=tokyo road;subset=yyy

Form 5
http://www.example.org/mwebcgi/mwebxml.exe?request=advanced;_t1101=tokyo road;subset=yyy;subset=yyy2
Usage

Use Form 1 to search for two keywords in the specified Search Category.

Use Form 2 to search for a phrase in the specified Search Category.

Use Form 3 to include start and end dates in the search (1800 - 1880 in this example).

Use Form 4 to restrict a search to a Subset.

Use Form 5 to restrict a search to multiple subsets.

Change "www.example.org" to the site's URL.

Add the Content-Type/value pairs as shown. There is no maximum number, but each one slows down the search.

Words or phrases to be searched as a phrase must be within double quotes, like this:

... _t1101="tokyo road"; ...

Change yyy to the Subset to be searched, as found using the Search Categories request.

Add the parameter "dtype=i" to the request to retrieve only records with images.

Response Same as for Keyword Search.

Hierarchy List

Retrieves a list of all hierarchies. Some sites organize their hierarchies under a common root, in which case you will probably not show the results of this request to the user, but use it only to get the key of the root term in order to use it in a Hierarchy request. However, if the site does not have a root term, as in this example, then you would show the results of the Hierarchy List request to the user for further selection.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=hierlist
Usage Change "www.example.org" to the site's URL.
Response
<hierarchies count="34">
  <hierarchy key="120189">
    <name>African Art</name>
  </hierarchy>
  <hierarchy key="120105">
    <name>American Art</name>
  </hierarchy>
  <hierarchy key="120122">
    <name>Ancient Near Eastern Art</name>
  </hierarchy>
  ...
</hierarchies>
Remarks The list is returned in alphabetical order.

Hierarchy

Retrieves a hierarchy of terms. This may be an entire hierarchy or a branch, depending on the key sent in the request.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=hier;key=yyy
Usage Change "www.example.org" to the site's URL.

Change yyy to the Key of the desired hierarchy
Response
<hierarchy>
  <term key="120105" id="500275" type="803" level="0" count="0">
    <name>American Art</name>
  </term>
    <term key="119893" id="500752" type="801" level="1" count="0">
      <name>Browse by Selected Topics</name>
    </term>
      <term key="120188" id="500975" type="801" level="2" count="15">
        <name>Artists and Daily Life</name>
      </term>
        <term key="120163" id="500802" type="802" level="3" count="42">
          <name>Art of Everyday Life</name>
        </term>
      <term key="120008" id="500801" type="801" level="2" count="12">
        <name>Artists and Identity</name>
      </term>
  ...
</hierarchy>
Remarks The list is returned in tree order.

You should inactivate terms that have no records linked to them (that is, when count is 0) so they do not generate a Hierarchy Search, because if the user clicks on a term with no records linked to it, a warning is generated.

Hierarchy Search

Retrieves the records that are linked to a specific term in a hierarchy. Only Primary Records are retrieved (objects, artworks, library records, archives, photos, etc.), not documents, other terms, Online Exhibits, etc.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=hiersearch;key=yyy

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=hiersearch;key=yyy;dtype=i
Usage Use Form 1 to retrieve all records linked to the term.

Use Form 2 to retrieve only records with images.

Change "www.example.org" to the site's URL.

Change yyy to the Key of the desired term
Response Same as for Keyword Search.

Exhibit List

The Exhibit List request returns a list of all Online Exhibits in the system (including Flash OEs). This can be used to prepare a list of selections for the user. As with all other lists of brief records, only the first Groupsize are returned with data; the remainder are returned as Placeholder Records.

The example in the table below shows an Exhibit List containing one traditional OE and one Flash OE.

A Flash OE cannot be requested using the Exhibit request (below). Flash OEs are identified by being in Subset 950; thus they will be returned after the list of standard OEs.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=exhibitlist
Usage Change "www.example.org" to the site's URL
Response
<exhibitlist count="2">
  <subset db="1" id="900" name="Exhibitions">
    <record key="12345" id="1003" type="901">
      <image>
        <thumbnail>http://www.example.org/mwebgraphics/1003.jpg</thumbnail>
      </image>
      <Title><a href="/mwebcgi/mwebxml.exe?request=exhibit;id=1003">Luxury Textiles East & West</a></Title>
      <Department>Costume & Textiles</Department>
      <Start_date>2003-02-20</Start_date>
      <End_date>2004-02-29</End_date>
      <Description>Luxury Textiles East and West celebrates the department's fiftieth
                 anniversary by highlighting a number of its finest treasures in a three part 
                 thematic presentation.</Description>
      <Credit>This exhibition was organized by the Los Angeles County Museum of Art.</Credit>
    </record>
  </subset>
  <subset db="1" id="950" name="Flash Exhibitions">
    <record key="44333" id="1221" type="951">
      <image>
        <thumbnail>http://www.example.org/mwebgraphics/1221.jpg</thumbnail>
      </image>
      <Title><a href="/mwebcgi/mwebxml.exe?request=flash;id=1221">Modern Netsuke</a></Title>
      <Department>Japanese Art</Department>
    </record>
  </subset>
</exhibitlist>
Remarks The fields returned and their names are a site option.

The thumbnail image is an icon that may be used for the Exhibit; it has no full-size image.

Favorites

There is more about Favorites below.

This request returns either:

  • A list of a user's sets of Favorites (Form 1).
  • The contents of a single set of Favorites (Form 2). Only public records are returned.

Warning: The user's logon ID and password are not verified by MXS. Your application should do so before retrieving Favorites for a user.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=favorites;owner=yyy

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=favorites;owner=yyy;title=zzz

Form 3
http://www.example.org/mwebcgi/mwebxml.exe?request=favorites;owner=yyy;title=zzz;dtype=d

Form 4
http://www.example.org/mwebcgi/mwebxml.exe?request=favorites;owner=yyy;title=zzz;dtype=i
Usage Change "www.example.org" to the site's URL

Change yyy to the ID of the user who owns the set of Favorites

Change zzz to the title of the set to be retrieved

Response If there is no title parameter in the request (Form 1), the response is a list of titles:
<favorites count="3">
  <title>
    <title>My favorite artworks</title>
    <remarks>Created for Art 101</remarks>
    <count>35</count>
  </title>
  <title>
    <title>Study collection</title>
    <count>23</count>
  </title>
  <title>
    <title>Italian marble</title>
    <remarks>Ask George about this</remarks>
    <count>12</count>
  </title>
</favorites>
If there is a title parameter in the request (Form 2, 3, or 4), the response is the normal Search Results display (including the limitation of 12 records unless you override that with the number parameter), except that the top-level tag is like this:
<favorites title="My favorite artworks" remarks="Created for Art 101" count="35">
Forms 2 and 3 return all public records in the set; the two Forms perform identically.

Form 4 returns only records with public images.

Remarks The count of records in a set returned from Form 1 may include non-public records. The count returned from Forms 2, 3, and 4 is the count of records returned.

Record Requests & Responses

For clarity, the URLs shown below for requests do not include the Caller parameter, an MXS security measure. Please see Security and Privacy for details.

Full Record

Returns data for a single record. The data consists of all fields that the site wishes to have displayed for the record, plus identification data for all images and media.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=record;key=www

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=record;id=yyy;type=zzz
Usage Use Form 1 when you know the MWeb Key for the record (but remember that the MWeb Key is not a permanent identifier; Keys are reassigned when the database is rebuilt).

Use Form 2 when you know the site's unique ID for the record (see Keys, IDs, and Types, above).

Change "www.example.org" to the site's URL

Change yyy to the site's unique ID for the record

Change zzz to the Content Type of the record
Response
<record key="4544" id="M.82.150.34a-c4" type="101">
  <images>
    <image>
      <descriptor>back view</descriptor>
      <copyright>Copyright 1988</copyright>
      <thumbnail>http://www.example.org/mwebimages/cat01_001/thumb/M85_77_4.jpg</thumbnail>
      <fullimage>http://www.example.org/mwebimages/cat01_001/full/M85_77_4.jpg</fullimage>
    </image>
    <image>
      <descriptor>side view</descriptor>
      <copyright>Copyright 1988</copyright>
      <thumbnail>http://www.example.org/mwebimages/cat01_001/thumb/M85_77_4_side.jpg</thumbnail>
      <fullimage>http://www.example.org/mwebimages/cat01_001/full/M85_77_4_side.jpg</fullimage>
    </image>
  </images>
  <Artist><a href="/mwebcgi/mwebxml.exe?request=record;id=61212;type=701">
                      Toyohara Kunichika</a></Artist>
  <Artist><a href="/mwebcgi/mwebxml.exe?request=record;id=43444;type=701">
                      Utagawa Kunisada (Toyokuni III), Japan, 786-1864</a></Artist>
  <Title><i>The Sixth Month</i></Title>
  <Series>Scenes of the Twelve Months: Water, Plum, and Moon</Series>
  <Date>circa 1854</date>
  <Medium_Technique>Triptych; color woodblock prints</Medium_Technique>
  <Dimensions>Overall: Image: 14 3/16 x 29 in. (36.0 x 75.4 cm)</Dimensions>
  <Museum_Number>M.82.150.34a-c</Museum_Number>
  <Classification_Term>Print</Classification_Term>
  <Credit_Line>Gift of Lyle and Marie Fair</Credit_Line>
  <Department>Japanese Art</Department>
  <Place>Japan</Place>
</record>
Remarks Fields are returned in the order specified by the site.

All images for the record are returned in the order specified by the site.

At present, links to media are not returned.

Field

This request returns the name and contents of a field. Fields in MWeb are uniquely identified by an integer; since the fieldname may change, this integer is used for stability. Furthermore, each site uses different integers. Ask us for the integers for the fields you need to retrieve.

If there are multiple fields with the same integer (such as in the case where an artwork has multiple artists), all are retrieved.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=field;key=yyy;field=fff

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=field;id=zzz;type=ttt;field=fff
Usage Change "www.example.org" to the site's URL

Change yyy to the unique MWeb key of the record, or use the permanent ID (zzz) and record type (ttt)

Change fff to the number of the desired field.
Response
<field count="2">
  <instance>
    <fieldname>Artist</fieldname>
    <value><a href="?request=record;id=22798;type=701">Frederick Hurten Rhead </a>(England, 1880 - 1942)</value>
  </instance>
  <instance>
    <fieldname>Artist</fieldname>
    <value><a href="?request=record;id=19;type=701">American Encaustic Tiling Company</a></value>
  </instance>
</field>

Exhibit

This is the request for an MWeb Online Exhibit (OE). Unlike the exhibit request in MWeb Enterprise, which displays the Online Exhibit, in MXS it retrieves the data for the OE which your application can then display.

This request cannot be used to retrieve the contents of a Flash OE.

An OE consists of the following components

  • Terms, used to generate a hierarchical menu that reflects the structure of the OE. Terms are of two types:
    • Sections are the parts of the OE which have HTML Documents describing them (didactic text). They correspond to sections of a real exhibit that may consist of several rooms. When the user clicks on a Section, you should display the corresponding Document and associated Objects.
    • Galleries are the parts of Sections that do not have their own Documents. When the user clicks on a Gallery, you should display the associated Objects without changing the Document.
    Sections are displayed in the menu, Galleries are not, but instead are accessed from links in the Documents.
  • Documents, HTML documents that are linked to the Terms. When the user clicks on a Term, you should display the associated Document. (Documents are not stored in the MWeb Enterprise Database, and are not transmitted in the XML, only their URLs. In other words, they are static pages on your server.) Documents may have Galleries, which are links inside the Documents. When the user clicks a Gallery link, the set of object that is displayed or highlighted changes.
  • Objects, the objects in the exhibit. These are linked to specific terms, so when the user clicks on a term, the set of objects displayed can change or be highlighted.

The document MWeb Online Exhibits explains the data in more detail, as well as the HTML interface provided by MWeb.

Request
Form 1
http://www.example.org/mwebcgi/mwebxml.exe?request=exhibit;key=yyy

Form 2
http://www.example.org/mwebcgi/mwebxml.exe?request=exhibit;id=yyy
Usage Use the first form when you know the MWeb Key for the record (but remember that the MWeb Key is not a permanent identifier; Keys are reassigned when the database is rebuilt)

Use the second form when you know only the site's unique ID for the record.

Change "www.example.org" to the site's URL

Change yyy to the Key or ID of the exhibit

Response
<exhibit>
  <term level="1" key="85459" gallery="0" popup="0">
    <name>Luxury Textiles East and West</name>
  </term>
  <term level="2" key="85445" gallery="0" popup="0">
    <name>Introduction</name>
    <document>http://www.example.org/mweb/ct/luxtex/introduction.htm</document>
    <object key="6565">
      <label>Buddhist Priest&#8217;s Robe (Sengjiazhi) with Dragons</label>
      <images>
        <image>
          <description>back view</description>
          <thumbnail>http://www.example.org/mwebimages/cat01_001/thumb/M85_77_4.jpg</thumbnail>
          <fullimage>http://www.example.org/mwebimages/cat01_001/full/M85_77_4.jpg</fullimage>
        </image>
        <image>
          <description>side view</description>
          <thumbnail>http://www.example.org/mwebimages/cat01_001/thumb/M85_77_4_side.jpg</thumbnail>
          <fullimage>http://www.example.org/mwebimages/cat01_001/full/M85_77_4_side.jpg</fullimage>
        </image>
      </images>
    </object>
    <object key="6578">
      <label>Round Badge (Lizi) of the Hereditary Prince Military Rank with a Dragon</label>
      <images>
        <image>
          <thumbnail>http://www.example.org/mwebimages/cat0787/thumb/99_77_22.jpg</thumbnail>
          <fullimage>http://www.example.org/mwebimages/cat0787/full/99_77_22.jpg</fullimage>
        </image>
      </images>
    </object>
  </term>
</exhibit>
Remarks The level-1 term is the Exhibit title.

The Terms are generated from the MWeb Database; a hand-made table of contents (which MWeb can substitute for a generated table of contents) will not be returned. Use the same hand-made table of contents in your application if required.

Utility Requests & Responses

For clarity, the URLs shown below for requests do not include the Caller parameter, an MXS security measure. Please see Security and Privacy for details.

Content Types

Similar to a record-type in other systems, an MWeb Content Type is a distinct type of record that is loaded into the system. Examples of Content Types are: museum objects, library records, artists, places, periods and styles, images, media, HTML documents, etc. The Content Type is required to specify a Full Record when using the site's unique ID (because the site's IDs may not be unique across Content Types).

This request returns all the MWeb Content Types used by the site. Content Types are three-digit numbers. The names are the terms used to describe them by that site. (Both the numbers and the terms can vary from site to site.)

In addition, this request returns the Subset that each Content Type belongs to.

See also the Subsets request.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=contypes
Usage Change "www.example.org" to the site's URL
Response
<contypes count="5">
  <contype>
    <contype>101</contype>
    <name>Permanent Collection Object</name>
    <subset>100</subset>
  </contype>
  <contype>
    <contype>102</contype>
    <name>Study Collection Object</name>
    <subset>100</subset>
  </contype>
  <contype>
    <contype>201</contype>
    <name>General Library</name>
    <subset>200</subset>
  </contype>
  <contype>
    <contype>202</contype>
    <name>Reference Library</name>
    <subset>200</subset>
  </contype>
  <contype>
    <contype>401</contype>
    <name>Finding Aid</name>
    <subset>400</subset>
  </contype>
</contypes>

Record Key

This request returns the MWeb Key, which is MWeb's unique internal identifier for a record, from the record's ID and Type, which are the permanent identifiers based on the site's data. This is a utility function for times when the Key may be needed.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=recordkey;id=yyy;type=zzz
Usage Change "www.example.org" to the site's URL

Change yyy to the site's unique identifier for the record

Change zzz to the Content Type of the record

Response
<recordkey>
  <key>12345</key>
</recordkey>
Remarks By definition, only a single Key should be returned by this request.

Subsets

Subsets are groupings of similar Content Types. Their purpose is to enable a search to be limited to specific kinds of materials without having to specify each Content Type in the query. For example, a Subset might include all kinds of objects, or all kinds of library records. This request shows what Subsets are used in the site's MWeb database.

Usually, Subset numbers are the Content Type numbers rounded to the nearest 100. That is, Subset 100 would include Content Types 101, 102, etc. Exceptions to this rule occur in some installations.

This request returns all the MWeb Subsets used by the site. Subsets are three-digit numbers. The names are the terms used to describe them by that site. (Both the numbers and the terms can vary from site to site.)

See also the Content Types request.

Request
http://www.example.org/mwebcgi/mwebxml.exe?request=subsets
Usage Change "www.example.org" to the site's URL
Response
<subsets count="3">
  <subset>
    <subset>100</subset>
    <name>Museum Objects</name>
  </subset>
  <subset>
    <subset>200</subset>
    <name>Library Materials</name>
  </subset>
  <subset>
    <subset>400</subset>
    <name>Finding Aids</name>
  </subset>
</subsets>

Other Information

Security and Privacy

MXS has several features that provide a high level of security for your data:

  • MXS is unable to write to, update, or delete from your MWeb Enterprise Database. Your application should not attempt this either: it both violates the license and will lead to data corruption. Tables that require updates, such as to save Favorites, are stored in a separate database. (There is more information about Favorites in next section.)
  • At present, only data and images with public-level security can be retrieved. Images and data that are restricted to users with a higher level of security are simply not retrieved. See the MWeb Security Model for details.
  • MXS incorporates encrypted handshake and timestamp information to ensure it is being called by an authorized application and is running on an authorized server.
  • SQL injection attacks are prevented.

Please note that MXS does not check user IDs and passwords; this is the responsibility of the application requesting service from MXS. Because of this, the privacy on users' lists of Favorites is not high. Anyone could enter a URL and view a user's Favorites.

Caller

Another security feature of MXS is the Caller parameter. This is a 40-byte encrypted string that we will provide you to reduce the likelihood of unauthorized frontends accessing the database. You should add this string to the URL of each request; these are not shown in the examples above for clarity. Here is an example showing an (invalid) Caller parameter:

http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=tokyo;caller=A8348KLAFU894UJAF89048U34ILJKLJAFLKA8934

Favorites

Favorites is the MWeb term for a list of records that are saved by users. These are stored in separate SQLite files, one file per user. MXS can retrieve from these files using the Favorites request. Since MXS has no ability to write to data files (a design decision to ensure security), if you want to allow users to add to or update their Favorites, your application must update the SQLite files. We will provide the data model of the Favorites files on request.

In MWeb Flash, which is written in Adobe Flex 2, calls are made to the MWeb Enterprise CGI program to do this. However, Flex 3 can write to SQLite files, and MWeb Flash will be upgraded to Flex 3 so it can manage Favorites directly. This will provide a model of how to manage Favorites using Flex.

A set of Favorites can include non-public records and images, if the set was created by someone with a higher level of permission. However, because MXS can retrieve only public data and images, the non-public records and images will not be retrieved. This might mean fewer records are retrieved than the count of records in the set.

Data-Source Names

MXS assumes the ODBC Data-Source Name (DSN) is "MWEB". If the MWeb database uses some other DSN, include it as a parameter in the request:

http://www.example.org/mwebcgi/mwebxml.exe?dsn=mydsn;request=keyword;keyword=yyy

Displaying Images

For Search Results, the image the site designated as the first image for that record is returned. For Full Records, all images are returned. In all cases, MXS returns the full URLs for both the thumbnails and the full-size images. With full URLs, it is easy to display the thumbnail as a clickable link to the image.

Resizing images

In MWeb Enterprise, we use Javascript called by the image onload method to resize images when they are first displayed. You may wish to add logic for this to your application.

Image Paths

At present, MXS assumes that images are stored using the recommended /Full/ and /Thumb/ subdirectories. There may or may not be subdirectories under /MWebimages/ for departments or other groupings. In other words, either of these structures may occur, but the second one is used only if the site has very few images.

          MWebimages                       MWebimages
           |                                |
           |- Paintings                     |- Full
           |   |                            |
           |   |- Full                      |- Thumb
           |   |
           |   |- Thumb
           |
           |- Sculpture
           |   |
           |   |- Full
           |   |
           |   |- Thumb
           |
           |- etc.
               |
               |- Full
               |
               |- Thumb

MWeb Help File

The MWeb Help file, written for the end-user, is not generally needed, except for the syntax of Advanced Search requests. However, it also discusses Keyword Search, performance issues, and other relevant information. The text of this Help file is freely available for you to incorporate into your own Help file. You may change the text if you wish, or use it as it is.

Error Handling

If an error occurs while MXS is processing your application's request, it returns a response containing error information. Depending on the severity of the error, the response may also contain some or all of the data your application requested.

Errors are of two severity levels: Critical and Warning. An example of a Critical Error would be if your application requested a Full Record but did not provide the Key or the ID and Type; obviously MXS cannot return the requested Full Record. Here is an example of this response:

<record>
  <errors>
    <error>
      <severity>Critical</severity>
      <message>X022: Missing Key or ID and Type</message>
    </error>
  </errors>
</record>

The Critical severity means that MXS could not process the request.

The Warning severity means that MXS tried to process the request but some unusual condition arose. In this case the errors are shown first, and the response data afterwards, as in this example:

<record>
  <errors>
    <error>
      <severity>Warning</severity>
      <message>X123: Record is missing mandatory field 'Title'</message>
    </error>
    <error>
      <severity>Warning</severity>
      <message>X123: Record is missing mandatory field 'Date'</message>
    </error>
    <error>
      <severity>Warning</severity>
      <message>X123: Record is missing mandatory field 'Medium_Technique'</message>
    </error>
  </errors>
  <Artist request="record" key="61241" id="T355" type="701">Toyohara Kunichika, Japan, 1835-1900</Artist>
  <Artist request="record" key="61776" id="U784" type="701">Utagawa Kunisada (Toyokuni III), Japan, 786-1864</Artist>
  <Series>Scenes of the Twelve Months: Water, Plum, and Moon</Series>
  <Dimensions>Overall: Image: 14 3/16 x 29 in. (36.0 x 75.4 cm)</Dimensions>
  ...
</record>

In some cases an error must be generated before the appropriate top-level element has been constructed; in order to maintain the same structure, a dummy top-level element of <response> is used, as in this example:

<response>
  <errors>
    <error>
      <severity>Critical</severity>
      <message>M113: Could not connect to 'MWeb' data source</message>
    </error>
  </errors>
</response>

As you can see, it is essential that your application check each response to see if there are errors. We make this easy by always inserting <errors> as the first element under the top-level element whenever there is an error of any kind.

We suggest that the <message> text be displayed to the user so that the error can be corrected or at least reported. Please include the message number in the display if you expect us to help with diagnosis.

Error numbers

Each error in the MWeb system has a unique identifier. This enables us to locate the precise cause of the error when it is reported to us. Although the text of messages may change over time, the numbers do not (although they may be removed if no longer useful). Because the numbers do not change over time, you may design your application to handle errors automatically based on the numbers.

Here is a link to the list of MWeb messages and their meanings.

Planned Enhancements

The following enhancements are planned:

  • Additional data added to the Full Records to implement "Next Record" and "Previous Record" buttons. In the meantime, you may implement this by using the information in the Search Results.

Legal Matters

"MWeb", "MWeb XML Server", and "MXS" are trademarks of Systems Planning.

Use of MXS is governed by the MWeb Online Catalog System Software License Agreement. Among other matters, it specifies that each display must contain the following message and link:

This site uses the <a href="http://systemsplanning.com/mweb/credits.asp">MWeb™ XML Server</a>.

The trademark symbol is critical. Use &trade; or &#8482; to display the trademark symbol.

The initial display must present this link so that a user with an 1024x768 monitor can see it without scrolling.

The license also specifies that the Systems Planning URL (systemsplanning.com) be provided when mention is made of MWeb in papers, talks, or presentations to museum audiences.