The Virtual Shelf Index (VSI) Web Service can support a variety of applications. At its heart is an index of library catalog records that are stored and can be retrieved in call number order. Entry into a specific point in the index can be made by supplying a call number, a catalog key, or a classification type.
The VSI Web Service is really two different services: VSI Start, which facilitates entry into the index; and VSI Slice, which retrieves sets of records in call number order.
Requests are accepted over HTTP and responses are provided over HTTP as JSON.
Under normal circumstances, the ingest script will be run automatically at a regular interval to ingest the latest set of sirsi records into the database for the index.
web/var/www/live/htdocs/catalog/virtualshelfindex/scripts
/opt/coolstack/bin/python vs_index_ingest_calling_app.py
The ingest script may generate a fatal error if it cannot connect to the database, if it cannot locate a sirsi file for ingest, or if the number of rows in the new table are more than 5% larger or smaller than the production table. In any of these cases the production table will remain in production and will not be dropped or replaced. In the case that the new table is too large or too small, you may force the new table to replace the production table by running the script from the command line with the force -f flag, as follows:
/opt/coolstack/bin/python vs_index_ingest_calling_app.py -f
The VSI Start service accepts a Call Number, Catalog Key, or Classification Type and returns a Batch ID.
http://www.lib.ncsu.edu/catalog/virtualshelfindex/start
The base request returns the Batch ID that appears at the beginning of the Index.
{"results":[{"batchId":"0"}],"parameters":{"classType":"LC"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start"}
If a Batch ID cannot be returned the service responds with an error.
{"results":[],"parameters":{"catKey":"1"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start","error":"emptyResult"}
| parameter | default value | note |
|---|---|---|
| callNum | N.A. | forgives spaces |
| classType | LC | accepts LC or SUDOC; otherwise reverts to LC |
http://www.lib.ncsu.edu/catalog/virtualshelfindex/start?callNum=P100&classType=LC
The response will include the Batch ID of the specified call number or the closest match. When a Call Number parameter is supplied the service first attempts to find a call number in the index that starts with the same sequence of characters (spaces are ignored). If there is not a call number in the index that starts with the parameter supplied, the service attempts to return the closest matching record in the index.
{"results":[{"batchId":"620727"}],"parameters":{"callNum":"P100","classType":"LC","matchType":"startsWith"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?callNum=P100&classType=LC"}
{"results":[{"batchId":"620744"}],"parameters":{"callNum":"P9999","classType":"LC","matchType":"closestMatch"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?callNum=P9999&classType=LC"}
If a Batch ID cannot be returned the service responds with an error.
{"results":[],"parameters":{"catKey":"1"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?callNum=P9999&classType=LC","error":"emptyResult"}
| parameter | default value | note |
|---|---|---|
| catKey | N.A. | accepts positive integers <= 999999999999999; otherwise reverts to 0 |
http://www.lib.ncsu.edu/catalog/virtualshelfindex/start?catKey=78932
The response will include the Batch ID of the specified Catalog Key. Catalog Key parameters are matched exactly. If the specified Catalog Key does not exist in the Index an error will be returned.
{"results":[{"batchId":"1236805"}],"parameters":{"catKey":"78932"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?catKey=78932"}
If a Batch ID cannot be returned the service responds with an error.
{"results":[],"parameters":{"catKey":"1"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?catKey=1","error":"emptyResult"}
| parameter | default value | note |
|---|---|---|
| classType | LC | accepts LC or SUDOC; otherwise reverts to LC |
http://www.lib.ncsu.edu/catalog/virtualshelfindex/start?classType=SUDOC
The response will include the Batch ID of the record at the beginning of the classification specified.
{"results":[{"batchId":"1321577"}],"parameters":{"classType":"SUDOC"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?classType=SUDOC"}
If a Batch ID cannot be returned the service responds with an error.
{"results":[],"parameters":{"catKey":"1"},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/start?classType=SUDOC","error":"emptyResult"}
| key | values | note |
|---|---|---|
| results | a list of dictionaries | this contains the results of the query |
| batchId | a positive integer | indictates the record's position in the index |
| parameters | a dictionary | specifies the system or user applied parameters that generated the results |
| callNum | any string | specifies the call number string applied to the query |
| matchType | startsWith or closestMatch | system determined query type; startsWith is a LIKE query, closestMatch is a comparison query |
| catKey | a positive integer <= 999999999999999 | specifies the catalog key parameter applied to the query |
| classType | LC or SUDOC | specifies the classification parameter applied to the query |
| requestUrl | a URL | specifies the complete URL sent to web service that generated the response |
| error | emptyResult | only appears if a result cannot be provided |
The VSI Slice service accepts a Batch ID and returns a set of Catalog Keys in Call Number order.
The base request returns an ordered set of 20 records starting from the beginning of the index.
http://www.lib.ncsu.edu/catalog/virtualshelfindex/slice
{"results":[{"batchId":"0","catKey":"502416","minCallNum":"[ .Microfilm] .F251 N896 v.1-v.12:no.14"},{"batchId":"1","catKey":"1994674","minCallNum":"* ebook"},{"batchId":"2","catKey":"549862","minCallNum":"-631 .C62 v.47 NO.7-12 2006"},{"batchId":"3","catKey":"1563606","minCallNum":"B469 .L29 v.19 no.6, 11-12 2003"},{"batchId":"4","catKey":"1867283","minCallNum":"DA125 .A1 R87 2004"},{"batchId":"5","catKey":"2129815","minCallNum":"E806 .E63 2004 E-BOOK"},{"batchId":"6","catKey":"1744804","minCallNum":"HD1690.5 .I53 2001"},{"batchId":"7","catKey":"2129820","minCallNum":"HD4839 .S74 2004 E-BOOK"},{"batchId":"8","catKey":"315671","minCallNum":"HD9001 .P7"},{"batchId":"9","catKey":"1963134","minCallNum":"HD9235 .P8 E-BOOK"},{"batchId":"10","catKey":"296173","minCallNum":"HM1 .S62 new series v. 36 no.1-2 1988"},{"batchId":"11","catKey":"491320","minCallNum":"HN51 .J6 v.29 1950-1951"},{"batchId":"12","catKey":"1644750","minCallNum":"HT392.5 .N4 L58 2003"},{"batchId":"13","catKey":"290737","minCallNum":"J1313 .M42 1962 pt.2 JULY-DEC."},{"batchId":"14","catKey":"1887421","minCallNum":"JC571 .S2313 2005"},{"batchId":"15","catKey":"2129818","minCallNum":"KF154 .M35 2004 E-BOOK"},{"batchId":"16","catKey":"2129814","minCallNum":"KF4548 .E53 2000 E-BOOK"},{"batchId":"17","catKey":"1755596","minCallNum":"LA201 .E456 2004"},{"batchId":"18","catKey":"2049201","minCallNum":"LB2805 .S7424 2008"},{"batchId":"19","catKey":"1752163","minCallNum":"LT7715 .G55 A97 2004 V.1"},{"batchId":"20","catKey":"1371082","minCallNum":"ML74.4 .I47 B36 2000"}],"parameters":{"startBatch":0,"numBefore":0,"numAfter":20},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/slice"}
If the web service cannot serve the request the error response will return an empty set.
{"results":[],"parameters":{"startBatch":"789456123","numBefore":0,"numAfter":20},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/slice","error":"emptyResult"}
| parameter | default value | note |
|---|---|---|
| batchId | 0 | accepts positive integers <= 999999999999999; otherwise reverts to 0 |
| numBefore | 0 | accepts positive integers <= 9999; otherwise reverts to 0 |
| numAfter | 20 | accepts positive integers <= 9999; otherwise reverts to 20 |
http://www.lib.ncsu.edu/catalog/virtualshelfindex/slice?batchId=123123
{"results":[{"batchId":"123123","catKey":"237226","minCallNum":"DD176.8 .D52 1974b"},{"batchId":"123124","catKey":"436402","minCallNum":"DD177 .F8 O26"},{"batchId":"123125","catKey":"681830","minCallNum":"DD177 .P38 A4 1986"},{"batchId":"123126","catKey":"1539297","minCallNum":"DD178 .Y68 2000"},{"batchId":"123127","catKey":"1552429","minCallNum":"DD179 .B56 2002"},{"batchId":"123128","catKey":"380638","minCallNum":"DD179 .F4713"},{"batchId":"123129","catKey":"570918","minCallNum":"DD179 .M3418 1981"},{"batchId":"123130","catKey":"553508","minCallNum":"DD179 .O8 1968"},{"batchId":"123131","catKey":"77121","minCallNum":"DD179 .O813 1970"},{"batchId":"123132","catKey":"172858","minCallNum":"DD179 .R6 1972"},{"batchId":"123133","catKey":"530349","minCallNum":"DD179 .R60 1878 v.1"},{"batchId":"123134","catKey":"714563","minCallNum":"DD179 .R62 1988"},{"batchId":"123135","catKey":"395495","minCallNum":"DD179 .R63 1883 v.1-3"},{"batchId":"123136","catKey":"473843","minCallNum":"DD179 .R63 v.1-3"},{"batchId":"123137","catKey":"577922","minCallNum":"DD180 .H4 1983"},{"batchId":"123138","catKey":"508802","minCallNum":"DD180 .T92"},{"batchId":"123139","catKey":"362789","minCallNum":"DD180.5 .B72"},{"batchId":"123140","catKey":"1749872","minCallNum":"DD180.5 .K44 2004"},{"batchId":"123141","catKey":"189519","minCallNum":"DD180.5 .L43a"},{"batchId":"123142","catKey":"353672","minCallNum":"DD180.5 .M25 2002"},{"batchId":"123143","catKey":"564674","minCallNum":"DD180.5 .M44 1941"}],"parameters":{"startBatch":"123123","numBefore":0,"numAfter":20},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/slice?batchId=123123"}
If the specified batchId does not exist the error response will return an empty set.
{"results":[],"parameters":{"startBatch":"789456123","numBefore":0,"numAfter":20},"requestUrl":"http:\/\/webdev.lib.ncsu.edu\/virtualshelfindex\/slice?batchId=789456123","error":"emptyResult"}
| key | values | note |
|---|---|---|
| results | a list of dictionaries | this contains the results of the query |
| batchId | a positive integer | the record's position in the index |
| catKey | a positive integer | the catalog key associated with the batch ID |
| minCallNum | a call number | the minimum call number associated with the batch ID |
| parameters | a dictionary | specifies the system or user applied parameters that generated the results |
| startBatch | a positive integer <= 999999999999999 | specifies the batch ID applied to the query |
| numBefore | a positive integer <= 9999 | specifies the number of items requested to appear before the startBatch |
| numAfter | a positive integer <= 9999 | specifies the number of items requested to appear after the startBatch |
| requestUrl | a URL | specifies the complete URL sent to web service that generated the response |
| error | emptyResult | only appears if a result cannot be provided |