MWeb™ XML ServerThis document pertains to MWeb Enterprise and PastPerfect-Online only.
The MWeb XML Server (MXS) is a Web Service that generates XML from an MWeb Enterprise Database (including PastPerfect-Online) 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 and PastPerfect-Online, not with databases used by MWeb Universal.
Your application may be HTML pages, ASP pages, Flash movies, or anything else. MXS can work with your application in two ways:
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 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 < to <, > to >, " to ", and ' to '. For the latter, remove everything between the < and > 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.
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).
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 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"/>
...
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:
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.
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.
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.
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.
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.
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. |
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 Searching requires two request/response sequences, one to find out what fields are searchable, the other to request the search.
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:
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. |
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. |
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. |
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. |
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. |
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. |
There is more about Favorites below.
This request returns either:
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. |
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.
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. |
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>
|
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
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’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. |
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.
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>
|
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 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>
|
MXS has several features that provide a high level of security for your data:
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.
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 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.
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
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.
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.
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
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.
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.
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.
The following enhancements are planned:
"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:
The trademark symbol is critical. Use ™ or ™ 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.
All contents of website, including HTML and JavaScript, copyright © 1996-2010 Systems Planning. MWeb, InFORMer, and CAPS are trademarks of Selago Design, Inc. MARCView and MARConvert are trademarks of OCLC, Inc.
Systems Planning
Including the name of one of our products in the subject of your message will bypass all spam filters.