nlb open web service functional design specifications€¦ · 1.30 li lingxia 19 apr 2013 for...

NLB Open Web Service

Functional Design Specifications

Version: 1.00 For internal use of 57



Version: 2.30




Version History:

Version Author Date Change Note

1.00 Li Lingxia 29 Jun 2011 First version

1.10 Li Lingxia 12 Mar 2012 Add the Search web service

Remove the membership authentication service

1.20 Li Lingxia 25 Mar 2013 Remove the search web service

1.30 Li Lingxia 19 Apr 2013 For backend LMS upgrade

Add SetId in CatalogueService.Search and

CatalogueService.GetAvailabilityInfo

Change the mapping for code and description

1.40 Li Lingxia 9 May 2013 Add Singapore Memory Search REST service

2.00 Li Lingxia 6 May 2015 Add eResources API

2.10 Kayes Lim 23 Feb 2016 Updated eResources API

2.20 Kayes Lim 01 Oct 2016 Remove eJournal as sources for eResources API




Table of Content

Table of Content ...................................................................................................................................... 5

1 Description ....................................................................................................................................... 7

2 API Access Control ......................................................................................................................... 7

3 Web Service Description ............................................................................................................. 8

3.1 Catalogue Service ................................................................................................................... 8

3.1.1 Service Interface ............................................................................................................. 8

3.1.2 Method Description ...................................................................................................... 8

3.1.2.1 CatalogueService.Search ..................................................................................... 8

3.1.2.2 CatalogueService.GetTitleDetails ................................................................... 13

3.1.2.3 CatalogueService.GetAvailabilityInfo ............................................................ 16

3.2 Read Alike Service ................................................................................................................ 21

3.2.1 Service Interface ........................................................................................................... 21

3.2.2 Method Description .................................................................................................... 21

3.2.2.1 ReadAlikeService.GetRecommendationsForTitles .................................... 21

3.3 Singapore Memory Service ............................................................................................... 25



3.3.2.1 REST Search............................................................................................................ 25

3.4 Eresource Service .................................................................................................................. 29



3.4.2.1 EresourceService.Search .................................................................................... 29

3.4.2.2 EresourceService.GetAvailabilityInfo ............................................................. 35

3.4.3 Special Development Environment Consideration .......................................... 37

4 Code and Description Mapping ............................................................................................. 40

4.1 Title Level Media Code and Media Description Mapping ..................................... 40




4.2 Item Level Media Code and Media Description Mapping..................................... 40

4.3 Branch Code and Branch Name Mapping ................................................................... 42

4.4 Status Code and Status Description Mapping ........................................................... 43

4.5 Location Code and Location Description Mapping ................................................. 44

4.6 Sample Eresource ContentType and DataFrom Matrix .......................................... 46

5 Sample Implementation Codes ............................................................................................... 47

5.1 C# (.Net) ................................................................................................................................... 47




1 Description

This document lists the NLB Open Data API and their details.

Currently the following API are available from NLB Open Data Program.

Section API Methods

3.1 Catalogue Service CatalogueService.Search

CatalogueService.GetTitleDetails

CatalogueService.GetAvailabilityInfo

3.2 Read Alike Service ReadAlikeService.GetRecommendationsForTitles

3.3 Singapore Memory Service SingaporeMemoryService.Search

3.4 Eresource Service EresourceService.Search

EresourceService.GetAvailabilityInfo

Note:

SSL connection will only be available from 30 April 2016 onwards.

2 API Access Control

NLB Open Data API requires API Key for access for both Development and

Production APIs. API key can be obtained from http://www.nlb.gov.sg/labs/mash-

create-collaborate/

See section 5 Sample Implementation Codes for sample implementation of API call

with authentication.

http://www.nlb.gov.sg/labs/mash-create-collaborate/

http://www.nlb.gov.sg/labs/mash-create-collaborate/




3 Web Service Description

3.1 Catalogue Service

Catalogue Service provide interface to search NLB Catalogue database for books,

audio visual materials etc.

Please refer to Section 4 for code mapping used.

3.1.1 Service Interface

Production URL https://openweb.nlb.gov.sg/ows/CatalogueService.svc

Staging URL https://openweb-stg.nlb.gov.sg/ows/CatalogueService.svc

3.1.2 Method Description

Catalogue Service has 3 service methods:

Search – searching content according to search criteria

GetTitleDetails – getting the detailed information of an item

GetAvailabilityInfo – checking whether the item is available for loan

3.1.2.1 CatalogueService.Search

The following is a sample request message:

http://openweb.nlb.gov.sg/ows/CatalogueService.svc

http://openweb-stg.nlb.gov.sg/ows/CatalogueService.svc




<SearchRequest>

<APIKey></APIKey>

<SearchItems>

<SearchItem>

<SearchField>string</SearchField>

<SearchTerms>string</SearchTerms>

</SearchItem>

</SearchItems>

<Modifiers>

<SortSchema></SortSchema>

<StartRecordPosition>int</StartRecordPosition>

<MaximumRecords>int</MaximumRecords>

<SetId>string</SetId>

</Modifiers>

</SearchRequest>

Below is the description of request message:

Element Name Mandatory Data Type Description

APIKey Yes String The API Key to use NLB open

service.

SearchItems Yes Array Array of SearchItem, “AND”

operator when there is multiple

SearchItems.

SearchItem Yes Object





SearchItem.SearchField Yes String SearchField consists of

Keywords

Author

Subject

Title

At least one of Keywords, Author,

Subject or Title must be present

in a request. When all of them are

present, they will be processed

with AND operation.

SearchField can be augmented

with the following filters:

BranchID

MediaCode

Language

Filters are added using the same

tag as SearchField.

In the case of duplicated filters,

the last value will be used as the

final value.

Please refer to Section 4 for:

BranchID – Branch Code and

Branch Name Mapping

MediaCode – Title Level

Media Code and Media

Description Mapping

Language as below:

o English

o Chinese

o Malay

o Tamil

SearchItem.SearchTerms Yes String The search string for SearchField

Modifiers Yes Object





Modifiers.SortSchema No String The default value is empty string

which will return result ordered

by published year in descending

order.

Other possible values are:

PUBDATE – result ordered by

published year in ascending

order

TITLE – result ordered by title

in ascending order.

Note that articles like “a”,

“an” and “the” will be

ignored.

This will be extended if necessary.

Modifiers.StartRecordPosition No Integer Start pointer for returned records.

Default value is 1.

Modifiers.MaximumRecords No Integer Maximum records to be returned.

This is capped at 100 records

even if a number greater than

100 is specified.

Modifiers.SetId No String This is the Id of a cached

collection objects for use in

pagination.

The value is empty string for the

first page but subsequent page

will return the Id of the previous

page object.

This can be used with

StartRecordPosition to return the

index position of next record in

the backend system

The following is a sample response message:




<SearchResponse>

<Status>string</Status>

<Message>string</Message>

<ErrorMessage>string</ErrorMessage>

<TotalRecords>int</TotalRecords>

<NextRecordPosition>int</NextRecordPosition>


<Titles>

<Title>

<BID>string</BID>

<ISBN>string</ISBN>

<TitleName>string</TitleName>

<Author>string</Author>

<PublishYear>string</PublishYear>

<MediaCode>string</MediaCode>

<MediaDesc>string</MediaDesc>

</Title>

</Titles>

</SearchResponse>

Below is the description of response message:


Status Yes String Can be one of:

OK

FAIL

ERROR

FAIL indicates business error.

ERROR indicates system error.

Message Yes String When Status=OK, message is

“Operation completed

successfully"

Otherwise message is

"System error encountered. Please

contact the administrator"





ErrorMessage No String Error Message list for FAIL Status

Search Field cannot be

empty.

Search Terms cannot be

empty; minimum length is 2

characters.

Invalid Search Fields

TotalRecords Yes Integer The number of records matched

by the query. If the query fails this

will be 0.

NextRecordPosition Yes Integer The next position to get following

batch. If there are no remaining

records, this field will be set to 0.

SetId Yes String Refer the description in request

Titles No Array Array of Title

Title No Object Complex Type

Title.BID Yes String Bid for the item

Title.ISBN Yes String ISBN for the item

Title.TitleName Yes String Title of the item

Title.Author Yes String Author/creator of the item

Title.PublishYear Yes String Item publication year

Title.MediaCode No String Item media code

Title.MediaDesc No String Book media description for media

code.

Refer to Section 4 : “Title media

code and media description

mapping”

3.1.2.2 CatalogueService.GetTitleDetails





<GetTitleDetailsRequest>

<APIKey></APIKey>

<BID>string</BID>

<ISBN>string</ISBN>

</GetTitleDetailsRequest>




service.

BID Yes String It is mandatory for either one of

BID or ISBN to have value ISBN Yes String


<GetTitleDetailsResponse>




<TitleDetails>

<BID>string</BID>

<TitleName>string</TitleName>


<OtherAuthors>string</OtherAuthors>

<Publisher>string</Publisher>

<PhysicalDesc>string</PhysicalDesc>

<Subject>string</Subject>

<Subject>string</Subject>

<Summary>string</Summary>

<Notes>string</Notes>

<ISBN>string</ISBN>

<ISSN>string</ISSN>

<NTitleName>string</NTitleName>

<NAuthor>string</NAuthor>

<NPublisher>string</NPublisher>

</TitleDetails>

</GetTitleDetailsResponse>







OK

FAIL

ERROR





successfully"





BID or ISBN cannot be both

empty

BID only allow digit

BID is too long

(max length is 10)

This title is not available in

the system

TitleDetails.BID Yes String The Title ID.

TitleDetails.TitleName Yes String The title of the item.

(Marc data tag 245)

TitleDetails.Author Yes String The author of the item.

(Marc data tag 100)

TitleDetails.OtherAuthors No String The other authors/creator of

book.

(Marc data tag 710, separated by

‘|’)

TitleDetails.Publisher No String The Publisher of the item.

(Marc data tag 260)

TitleDetails.PhysicalDesc No String The Physical Description of the

item.

(Marc data tag 300)





TitleDetails.Subject No String The Subjects of the item.

(Marc data tag 650 is main

subject, 651 is sub subjects,

separated by ‘|’)

TitleDetails.Summary The summary for the item.

(Marc data tag 520)

TitleDetails.Notes Yes String The notes for the item.

(Marc data tag 500, tag 511)

TitleDetails.ISBN Yes String The ISBN for the item.

(Marc data tag 020)

TitleDetails.ISSN No String The ISSN for the item.

(Marc data tag 022)

TitleDetails.NTitleName No String The title of book in native

language.

(Marc data tag 880, start with

|6245)

TitleDetails.NAuthor No String The author of book in native

language.


|6100)

TitleDetails.NPublisher No String The Publisher of book in native

language.


|6260)

3.1.2.3 CatalogueService.GetAvailabilityInfo





<GetAvailabilityInfoRequest>

<APIKey></APIKey>

<BID>string</BID>

<ISBN>string</ISBN>

<Modifiers>





</Modifiers>

</GetAvailabilityInfoRequest>




service.

BID Yes String It is mandatory for either one of

BID or ISBN to have value ISBN Yes String

Modifiers Yes Object Refer to the description in Search

method.





<GetAvailabilityInfoResponse>




<NextRecordPosition>string</NextRecordPosition>


<Items>

<Item>

<ItemNo>string</ItemNo>

<BranchID>string</BranchID>

<BranchName>string</BranchName>

<LocationCode>string</LocationCode>

<LocationDesc>string</LocationDesc>

<CallNumber>string</CallNumber>

<StatusCode>string</StatusCode>

<StatusDesc>string</StatusDesc>



<StatusDate>string</StatusDate>

</Item>

</Items>

</GetAvailabilityInfoResponse>




OK

FAIL

ERROR





successfully"








ErrorMessage No String BID or ISBN cannot be both

empty


BID is too long

(max length is 10)

This title is not available in

the system

NextRecordPosition Yes String The next position to get following


records, this field will be set to

empty.

SetId Yes String Refer the Search method

Items No Array Array of Item

Item No Object Complex Type

Item.ItemNo Yes String Item Number (Barcode)

Item.BranchID Yes String Branch code for this item

Item.BranchName Yes String Branch name for this item. Refer

Branch ID and Name mapping

Item.LocationCode Yes String Location Code.

Item.LocationDesc Yes String Location Description. Refer to

Section 4 : “Location code and

location description mapping”

Item.CallNumber No String

Item.StatusCode No String Status Code.

Item.StatusDesc No String Status Description.

Refer to Section 4 : “Status code

and status description mapping.”

Item.MediaCode No String

Item.MediaDesc No String Book media description for media

code.

Refer to Section 4 : “Item level

media code and media

description mapping.”





Item.StatusDate No String The status date.

If item is not available, it is due

date. Otherwise it is last

transaction date.




3.2 Read Alike Service

Read Alike Service provides search of related titles to the one submitted in the

request message.

It is also known Title Recommendation Service.


Production URL https://openweb.nlb.gov.sg/ows/ReadAlikeService.svc

Staging URL https://openweb-stg.nlb.gov.sg/ows/ReadAlikeService.svc


Read Alike Service has only one service method:

GetRecomendationsForTitles – getting recommended content based on

searach criteria

3.2.2.1 ReadAlikeService.GetRecommendationsForTitles


<GetRecommendationsForTitlesRequest>

<APIKey>xxxxx</APIKey>

<BIDS>

<BID>string</BID>

<BID>string</BID>

</BIDS>

<BidType>NLB or ISBN</BidType>

<Modifiers>



<SelectionMode>Score or Random</SelectionMode>

</Modifiers>

</GetRecommendationsForTitlesRequest>


http://openweb.nlb.gov.sg/ows/ReadAlikeService.svc

http://openweb-stg.nlb.gov.sg/ows/ReadAlikeService.svc






service.

BID Yes Array of

String

List of BID

(Book Identification number)

BidType No Enumeration Values for NLB BID or ISBN

NLB

ISBN

Default Value is NLB

Modifiers.StartRecordPosition No Integer The start position for return list,

default value is 0.

Modifiers.MaximumRecords No Integer Maximum recommended books

to return according type. Value

from 1 to 30.

Default value is 5.

Modifiers.SelectionMode No Enumeration Pick Recommendations Selection

Algorithm Values:

Score - Highest score at first

Random – System random

pickup

Default value is Score.





<GetRecommendationsForTitlesResponse>




<Recommendations>

<Recommendation>

<BID>string</BID>

<Title>string</Title>

<NTitle>string</NTitle>


<NAuthor>string</NAuthor>

<ISBN>string</ISBN>



<Publisher>string</Publisher>

<PublishDate>string</PublishDate>

<Language>string</Language>

<Fiction>string</Fiction>

</Recommendation>

</Recommendations>

</GetRecommendationsResponse>




OK

FAIL

ERROR





successfully"









BID cannot be empty


BID is too long

(max length is 10)

Recommendations Yes Array Array of Recommendation

Recommendation No Complex

Type

RecommendationType Yes String System or LibrarianPick

BID Yes String BID for the book

Title No String Book title

NTitle Yes String Title in native language

Author No String Book author

NAuthor Yes String Author in native language

ISBN No String ISBN number

MediaCode No String Book media code.

MediaDesc No String Book media description for media

code.

Refer to Section 4.

Publisher No String

PublishDate No String Publication data

Language No String Language of the item

Fiction No String Y – Fiction

N – Non-fiction




3.3 Singapore Memory Service

The Singapore Memory Service allow search of Singapore Memory Project memory

donated by the public. Visit www.singaporememory.sg for more information about

the Singapore Memory Project.


Production URL https://openweb.nlb.gov.sg/REST/SM2/contents/search?

Staging URL https://openweb-stg.nlb.gov.sg/REST/SM2/contents/search?


Singapore Memory Service has only one REST service method:


3.3.2.1 REST Search


https://openweb-

stg.nlb.gov.sg/REST/SM2/contents/search?type=personal&nearby=-

118.2370170,34.0597670,0.5&tags=politics&keyword=alpha%20beta&sort=2&star

t=8&max=25




service. This should be sent in the

HTTP authentication header.

Please refer to “Using NLB Open

Data and Open Services.pdf”

Section 2.3.3.

http://www.singaporememory.sg/

http://openweb.nlb.gov.sg/REST/SM2/contents/search

http://openweb-stg.nlb.gov.sg/REST/SM2/contents/search

http://openweb-stg.nlb.gov.sg/REST/SM2/contents/search?type=personal&nearby=-118.2370170,34.0597670,0.5&tags=politics&keyword=alpha%20beta&sort=2&start=8&max=25







Parameters Yes String The following parameters are

supported, and the extension will

be implemented when necessary

later.

type – the type of content,

current only “personal” type

is supported.

nearby – the geocode with

radius for search centre,

format in the form of

longitude, altitude, radius in

km which is similar to Google

Map format (WGS84). e.g.

118.2370170, 34.0597670, 0.5

tags – the search terms in tag

field. e.g.

tag=leaders, Singapore

(terms are delimited by

commas)

keyword – keyword for

search. e.g.

keyword=alpha beta

Currently support one search

parameter only

sort – the result list sort

column,

o 1 – (by submission

date in descending)

o 2 – (by view count in

descending)

Default value is 1.

This is equivalent to

sortSchema in WS API.

The list will be extended

when necessary later.

start – the start record

number in integer. Default

value is 1.


startPosition in WS API.





max – the maximum records

to be returned.

Default value is 10.


maximumRecords in WS API.

The start and max parameters

are related and behave in

“page” mode.

Thus, the query with the

parameters will need to take

the following values:

o start = 1 or 11 or 21 or 31

if max = 10

o start = 1 or 21 or 41 or 61

if max = 20


<SearchResponse>

<Status>OK</Status>

<Message>Operation completed successfully</Message>

<ErrorMessage></ErrorMessage>

<TotalRecords>int</TotalRecords>

<NextRecordPosition>int</NextRecordPosition>

<Contents>

<Content>

<Id>f81d4fae-7dec-11d0-a765-00a0c91e6bf6</Id>

<Title>string</Title>

<Desc>string</Desc>

<ImagePath></ImagePath>

<DonorName></DonorName>

<LocationArea> longitude altitude </LocationArea>

<ViewCount></ViewCount>

</Content>

</Contents>

</SearchResponse>







OK

FAIL

ERROR





successfully"





001 – APIKey is invalid

002 – Parameter is invalid

003 – No matching record

Error Message list for ERROR

Status

901 – The database is not

available

Contents Yes Array Array of Content

Content No Complex

Type

Id Yes String Unique identifier

Title Yes String Title of the memory

Desc No String Description of the memory

ImagePath No String The URL to display content with

thumbnail.

DonorName No String Name of the Donor

LocationArea No String The format is in the form of

longitude, altitude

ViewCount No String The view count for this content




3.4 Eresource Service

Eresource Service provide the interface to search NLB e-content similar to NLB

OneSearch (http://search.nlb.gov.sg) but limited to only to electronic resources.


Production URL https://openweb.nlb.gov.sg/OWS/EresourceService.svc

Staging URL https://openweb-stg.nlb.gov.sg/OWS/EresourceService.svc


Eresource Service has 2 service methods:


GetAvailabilityInfo – checking whether the item is available for loan

(Currently only available for eBooks from Overdrive)

3.4.2.1 EresourceService.Search


http://search.nlb.gov.sg/

http://openweb.nlb.gov.sg/OWS/EresourceService.svc

http://openweb-stg.nlb.gov.sg/OWS/EresourceService.svc




<SearchRequest>

<APIKey></APIKey>

<SearchItems>

<SearchItem>

<SearchField>Title</SearchField>

<SearchTerms>The Singapore Story</SearchTerms>

</SearchItem>

</SearchItems>

<ContentType>eBooks</ContentType>

<DataFrom>Overdrive,Netlibrary</DataFrom>

<Modifiers>


<StartRecordPosition>0</StartRecordPosition>

<MaximumRecords>20</MaximumRecords>

</Modifiers>

</SearchRequest>




service.

SearchItems Yes Array Array of SearchItem, “AND” is

used between SearchItem

SearchItem Yes Object

SearchItem.SearchField Yes String Search field accepts below value

Title

Creator

(search fields are either

creator or contributor)

Publisher

Subject

Keywords

(search fields include title,

description, abstract, subject,

creator, contributor, source

or type)

SearchItem.SearchTerms Yes String The search string of search field





ContentType Yes String Content type. Please specify one

of the following:

eBooks

Magazines and Articles

Images

Records and Papers

Websites

eJournals

Refer to https://search.nlb.gov.sg

for more info on types.

DataFrom No String Accepts the combination of the

sample values below separated

by comma.

Wel

Overdrive

Ebrary

Netlibrary

NLB

Gale

Apabi

EBSCO*

This allow filtering for each

ContentType.

DataFrom value is case sensitive.

Please see Section 4 for more

sample values.

Modifiers Yes Object

Modifiers.SortSchema No String SortSchema accepts below value

Relevance

Date

Date Desc

Title

Creator

Default is Relevance.

http://search.nlb.gov.sg/





Modifiers.StartRecordPosition No Integer Starting pointer for returned

records. Default value is 0.

Modifiers.MaximumRecords No Integer Maximum records to be returned.

Default value is 10.

This is capped at 100 records

even if a number greater than

100 is specified.





<SearchResponse>




<TotalRecords>3022009</TotalRecords>

<NextRecordPosition>10</NextRecordPosition>

<Results>

<Result>

<ID>F3D4520D-3F1B-4FCD-8223-803573B3183D</ID>

<Types>

<Value>Electronic Book</Value>

</Types>

<Title>Serving a new nation [electronic resource] :

Baey Lian Peck’s Singapore story.. Ooi Kee Beng.</Title>

<Author>Kee Beng, Ooi.</Author>

<Abstracts>

<Value>Serving a new nation.</Value>

</Abstracts>

<Languages>

<Value>_Languages:English {18349056}</Value>

</Languages>

<CreationDate>12/31/2013 16:00:00</CreationDate>

<DataFrom>Overdrive</DataFrom>

<Url>https://opendata-

stg.nlb.gov.sg/eresources/?id=Lzgqztms04dKUVlNKfuLU5CN6mSLI+TqrohynjO0yqn

7SLrNQNTQ84/LvMzdrVXK63hCQmB06hkj0+OKxRTxmY5+GYmOrPPsVg5yuiY9pC/nRFS+fC0A

PfngxbF64jZALzgqztms04dKUVlNKfuLU5CN6mSLI+TqrohynjO0yqnIp7Ld7ktUtyaZqaPW9

mtMkYOx54DBhZY9x8INegaa3ApP/qKcIzl7</Url>

</Result>

</Results>

</SearchResponse>







OK

FAIL

ERROR





successfully"




ErrorMessage No String Error Error Message list for FAIL

Status

Search Field cannot be

empty.

Search Terms cannot be

empty, the length is at least 2

characters.

Search Field does not be

supported

Collection does not be

supported.

Sort Schema does not be

supported

TotalRecords Yes Integer The number of records matched

by the query. If the query fails this

will be 0.

NextRecordPosition Yes Integer The next position to get following


records, this field will be set to 0.

Results No Array Array of Result

Result No Object Complex Type

Result.ID Yes String The identifier ID for content.





Result.Types Yes Array of

String

The type of content.

Result.Title Yes String The title of content

Result.Author Yes String The author of content

Result.Abstracts No Array of

String

The Abstract of content

Result.Languages No Array of

String

The language of content

Result.CreationDate No String The date of creation.

Result.DataFrom Yes String The source of content.

e.g. Overdrive, WEL

Result.Url Yes String The detail page URL for content.

3.4.2.2 EresourceService.GetAvailabilityInfo

(Currently only available for eBooks from Overdrive)


<GetAvailabilityInfoRequest>

<APIKey></APIKey>

<ID>ec626d5a-b75c-44e2-83c5-df27ac1e9dd7</ID>

<DataFrom>Overdrive</DataFrom>

</GetAvailabilityInfoRequest>




service.

ID Yes String The identifier ID for content.





DataFrom Yes String The source only accepts below

value.

Overdrive

It will be extended if necessary


<GetAvailabilityInfoResponse>




<ID>ec626d5a-b75c-44e2-83c5-df27ac1e9dd7</ID>

<Title>Concertos [sound recording] / Mozart.</Title>

<TotalCopies>2</TotalCopies>

<TotalAvailableCopies>1</TotalAvailableCopies>

<TotalHoldCopies>0</TotalHoldCopies>

</GetAvailabilityInfoResponse>




OK

FAIL

ERROR





successfully"









DataFrom does not be

supported

The content does not exist

ID Yes String The identifier ID for content.

Title Yes String The title of content

TotalCopies Yes Integer The total copies.

TotalAvailableCopies Yes Integer The total available copies.

TotalHoldCopies Yes Integer The total on hold copies.

3.4.3 Special Development Environment Consideration

The result returned from ErsourceService.Search contains the metadata of matching

content and the URL to the actual content (e.g. link to eBooks in NLB content

provider website or link to article in NLB internal service point).

These URL may be outdated and inaccurate as the development API points to a

development search index database which may only be refreshed periodically.

Accessing outdated content may cause multiple issues or inaccurate testing during

development and content may get outdated frequently as NLB constantly add new

or remove expired e-content.

To work around this, NLB will be returning mock URL in the development search

result as depicted in the diagram below.

The mock URL will be hosted on https://www.nlb.gov.sg/labs/e-content-list/

http://www.nlb.gov.sg/labs/e-content-list/




In production environment, the search result will return actual URL that will be

redirected to the actual content as below.




4 Code and Description Mapping

4.1 Title Level Media Code and Media Description Mapping

Code Title Level Media Description

BK Books

CF Computer File

MP Maps

MU Music

MX Mixed Materials

SE Serials

VM Visual Materials

4.2 Item Level Media Code and Media Description Mapping

Code Item Level Media Description

BR Braille

BT Talking Book

CD Compact Disc

CDI Compact Disk Interactive

DVD Digital Video Disk

FS Filmstrip

KT Kit

M Music Scores

MAP Maps

MFC Microfiche

MFM Microfilm

MP Motion Picture

MV Videocassette

MVD Laser Disc





PA Art Print

PC Wall Chart

PIC Picture Collection

PS Flash Card

RD Recording Disk (LP Record)

RT Tape Recording (Cassettes)

ST Sculpture

TR Electronic Device(TR)

TS Tape Slide

VCD Video Compact Disc

MDPG Laser Disc (PG Rating)

MVPG Videocassette (PG Rating)

BOOK Book

VCPG Video Compact Disc (PG Rating)

MS Manuscript

CF Computer Files (CDRom or Disk)

EPHE Ephemera

CCL CCL Media Code

THS Thesis

SER Serials

DVPG Digital Video Disc (PG Rating)

POS Poster

MD16 Music Disc For NC16

MV16 Music Video For NC16

VC16 Videocassette For NC16

DV16 Digital Video For NC16

MD18 Music Disc For M18

MV18 Music Video For M18

VC18 Videocassette For M18





DV18 Digital Video For M18

MD21 Music Disc For R21

MV21 Music Video For R21

VC21 Videocassette For R21

DV21 Digital Video For R21

BD Blu-ray Disk

BDPG Blu-ray PG

BD16 Blu-ray NC16

BD18 Blu-ray M18

BD21 Blu-ray R21

4.3 Branch Code and Branch Name Mapping

Code Branch Name

TRL Tampines Regional Library

WRL Woodlands Regional Library

CMPL Clementi Public Library

LKCRL Lee Kong Chian Reference Library

AMKPL Ang Mo Kio Public Library

BBPL Bukit Batok Public Library

BPPL Bukit Panjang Public Library

BMPL Bukit Merah Public Library

CLL Central Public Library

CSPL Cheng San Public Library

CCKPL Choa Chu Kang Public Library

GEPL Geylang East Public Library

JRL Jurong Regional Library

JWPL Jurong West Public Library

QUPL Queenstown Public Library




Code Branch Name

TPPL Toa Payoh Public Library

YIPL Yishun Public Library

OCPL Library@Orchard

CNPL Library@Chinatown

SBPL Sembawang Public Library

LSC Library Supply Centre

SRPL Serangoon Public Library

LOLC NL Heritage

MPPL Marine Parade Public Library

BEPL Bedok Public Library

SKPL Sengkang Public Library

EPPL Library@Esplanade

MOLLEY Mobile Bus

PRPL Pasir Ris Public Library

BIPL Bishan Public Library

LSCAV Library Supply Centre for AV

07LKCRL Lee Kong Chian Reference Library Level 7




4.4 Status Code and Status Description Mapping

Code Status Description

S On Shelf / Or For Reference Only

C Charged / On Loan

T Traced

L Lost

H Hold Shelf




I In Transit

IH In Transit Hold

R Item Hold or Recalled

SP In Process

R* Request Pending

4.5 Location Code and Location Description Mapping

Code Location Description

ALBK Adult Lending

ALSING Adult Lending Singapore Col.

AREF Reference

ARART Reference Art

ARBUS Reference Business

ARSING Reference Singapore

JLBK Junior Lending

JLPIC Junior Lending Picture Book

JLSFIC Junior Lending Simple Fiction

JREF Junior Reference

JRSING Junior Reference Singapore

YLBK Young adult Lending

YLSING Young adult Lending Singapore

YLSTU Young adult lending Student

YREF Young adult Reference

YRSING Young People Ref. Singapore

YRSTU Young People Ref. Student

RCLOSE Reference Closed Access

STAFFCOL Staff Collection

ACL Asian Children's Lit.

UNUSE UNUSE




Code Location Description

RRARE Reference Rare

RSEA Reference Southeast Asia

RACL Ref. Asian Children's Lit.

RDTYS Reference Donor Tan Yeok Seong

RAC Reference Asian Children

RAV Reference Audio-Visual

YRAV Young adult reference Audiovis

ALAV Adult lending Audiovisual

YLAV Young adult lending Audiovis.

JRAV Junior reference Audiovisual

JLAV Junior lending Audiovisual

LCLOSE Any age lend/ref closed stacks

RQUICK Quick Reference

JLSING Juvenile Lending Singapore

ATTBK Accompanying Item

ATTREF Accompanying Reference Item

RDTSH Reference Donor Tan Swie Hian

RCO Reference Chinese Overseas

RCR Reference China Resource

RDET Reference Donor Edwin Thumboo

RDKSC Reference Donor Koh Seow Chuan

RDLKL Reference Donor Lee Kip Lin

LREF Lending Reference

LRSING Lending RSING

ATTLR Accompanying Item for LR

ATTLRS Accompanying Item for LRSING




4.6 Sample Eresource ContentType and DataFrom Matrix

Please note that this is a case-sensitive field and will be extended with new values as

needed.

ContentType eBooks

Magazines

and

Articles

Images Records

and Papers

Websites eJournals

DataFrom Apabi

Ebrary

Gale

LMS

Netlibrary

NHB

NLB

Overdrive

Wel

LMS

NLB

LMS

NAS

NHB

NLB

LMS

NAS

NHB

NLB

NLB Not

applicable




5 Sample Implementation Codes

5.1 C# (.Net)

Below are C# sample codes for search function in Catalogue Service:

public void SearchBooks()

{

wcfCatalogueService.SearchItem searchItem = new SearchItem();

searchItem.SearchField = “Keywords“;

searchItem.SearchTerms = “whitemen”;

List<SearchItem> searchItemList = new List<SearchItem>();

searchItemList.Add(searchItem);

Modifiers mod = new Modifiers();

mod.StartRecordPosition = 1;

mod.MaximumRecords = 20;

wcfCatalogueService.SearchRequest request =

new wcfCatalogueService.SearchRequest();

request.APIKey = “XXXXXXXX”; //the NLB assigned Key

request.SearchItems = searchItemList.ToArray();

request.Modifiers = mod;

wcfCatalogueService.CatalogueServiceClient client =

new wcfCatalogueService.CatalogueServiceClient();

wcfCatalogueService.SearchResponse res = client.Search(request);

if (res.Status == "OK")

{

//process result list

} else

{

//exception handle

}

}//end of method

The following are sample codes for search function in Singapore Memory Service.




using System;

using System.Collections.Generic;

using System.Linq;

using System.Web;

using System.Web.UI;

using System.Web.UI.WebControls;

using System.Configuration;

using System.Net;

using System.Text;

public partial class SMTest2 : System.Web.UI.Page

{

string serviceURL = string.Empty;

protected void Page_Load(object sender, EventArgs e)

{

txtSearchResponse.Text = string.Empty;

txtGetDetailsResponse.Text = string.Empty;

txtAddMetaDataResponse.Text = string.Empty;

txtGetGUIDResponse.Text = string.Empty;

txtGDBProfileResponse.Text = string.Empty;

serviceURL =

ConfigurationManager.AppSettings["RESTServiceURL"].ToString();

}

protected void Search_Click(object sender, EventArgs e)

{

txtSearchResponse.Text = string.Empty;

try

{

string searchType = ddlSearchType.SelectedValue;

string searchTerm = string.Empty;

if (searchType == "nearby")

searchTerm = txtLatitude.Text + "," + txtLongitude.Text +

"," + txtDistance.Text;

else if (searchType == "type")

searchTerm = txtType.Text;




else if (searchType == "tags")

searchTerm = txtTags.Text;

else if (searchType == "keyword")

searchTerm = txtKeyword.Text;

else

{

searchType = "type";

searchTerm = "100";

}

string uri = string.Format("{0}/SM2/contents/search?{1}={2}",

serviceURL, searchType, searchTerm);

if (!string.IsNullOrEmpty(txtModifier.Text))

{

uri = uri + "&" + txtModifier.Text;

}

using (WebClient client = new WebClient())

{

client.Headers.Add("X-Authorization", txtAPIKey.Text);

client.Headers[HttpRequestHeader.UserAgent] =

txtAgent.Text;

txtSearchResponse.Text = client.DownloadString(uri);

}

}

catch (Exception ex)

{

txtSearchResponse.Text = "Exception : " + ex.Message;

}

}

protected void GetDetails_Click(object sender, EventArgs e)

{

txtGetDetailsResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/contents/search/{1}",

serviceURL, txtContentId.Text);





{



txtAgent.Text;

txtGetDetailsResponse.Text = client.DownloadString(uri);

}

}


{

txtGetDetailsResponse.Text = "Exception : " + ex.Message;

}

}

protected void AddMetaData_Click(object sender, EventArgs e)

{

txtAddMetaDataResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/contents/add/{1}",

serviceURL, txtId.Text);

StringBuilder data = new StringBuilder();

data.Append("<ContentMetaData

xmlns=\"http://ws.nlb.gov.sg/M/SM\">");

data.Append("<Title>");

data.Append(txtTitle.Text);

data.Append("</Title>");

data.Append("<Desc>");

data.Append(txtDesc.Text);

data.Append("</Desc>");

data.Append("<DisplayDate>");

data.Append(txtDisplayDate.Text);

data.Append("</DisplayDate>");

data.Append("<SubmitterId>");

data.Append(txtSubmitterId.Text);

data.Append("</SubmitterId>");




data.Append("<SubmitterName>");

data.Append(txtSubmitterName.Text);

data.Append("</SubmitterName>");

data.Append("<DonorName>");

data.Append(txtDonorName.Text);

data.Append("</DonorName>");

data.Append("<LocationArea>");

data.Append(txtLocationArea.Text);

data.Append("</LocationArea>");

data.Append("<CampaignUniqueTitle>");

data.Append(txtCampaignTitle.Text);

data.Append("</CampaignUniqueTitle>");

if (!string.IsNullOrEmpty(txtFileIds.Text))

{

string[] t = txtFileIds.Text.Split(new char[] { ',' },

StringSplitOptions.RemoveEmptyEntries);

if (t.Length > 0)

{

data.Append("<FileIDs>");

foreach (string s in t)

{

data.Append("<FileID>");

data.Append(s);

data.Append("</FileID>");

}

data.Append("</FileIDs>");

}

}

if (!string.IsNullOrEmpty(txtTag.Text))

{

string[] t = txtTag.Text.Split(new char[]{','},

StringSplitOptions.RemoveEmptyEntries);

if (t.Length > 0)

{

data.Append("<Tags>");

foreach (string s in t)




{

data.Append("<Tag>");

data.Append(s);

data.Append("</Tag>");

}

data.Append("</Tags>");

}

}

data.Append("</ContentMetaData>");


{



txtAgent.Text;

client.Headers[HttpRequestHeader.ContentType] =

"text/xml";

txtAddMetaDataResponse.Text = client.UploadString(uri,

"POST", data.ToString());

}

}


{

txtAddMetaDataResponse.Text = "Exception : " + ex.Message;

}

}

protected void GetGUID_Click(object sender, EventArgs e)

{

txtGetGUIDResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/contents/add",

serviceURL, txtContentId.Text);


{






txtAgent.Text;

txtGetGUIDResponse.Text = client.DownloadString(uri);

}

}


{

txtGetGUIDResponse.Text = "Exception : " + ex.Message;

}

}

protected void CheckGDBProfile_Click(object sender, EventArgs e)

{

txtGDBProfileResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/gdbprofile/{1}/{2}",

serviceURL, txtProvider.Text, txtProviderId.Text);


{



txtAgent.Text;

txtGDBProfileResponse.Text = client.DownloadString(uri);

}

}


{

txtGDBProfileResponse.Text = "Exception : " + ex.Message;

}

}

protected void btnUpdateSubmitter_Click(object sender, EventArgs e)

{

txtUpdateSubmitterResponse.Text = string.Empty;

try

{




string uri = string.Format("{0}/SM2/submitter/{1}",

serviceURL, txtSubProId.Text);

StringBuilder data = new StringBuilder();

data.Append("<Submitter

xmlns=\"http://ws.nlb.gov.sg/M/SM\">");

data.Append("<Name>");

data.Append(txtSubProName.Text);

data.Append("</Name>");

data.Append("<Email>");

data.Append(txtSubProEmail.Text);

data.Append("</Email>");

data.Append("<Notify>");

data.Append(txtSubProNotify.Text);

data.Append("</Notify>");

data.Append("</Submitter>");


{



txtAgent.Text;

client.Headers[HttpRequestHeader.ContentType] =

"text/xml";

//txtUpdateSubmitterResponse.Text =

client.UploadData(uri, "PUT",

Encoding.ASCII.GetBytes(data.ToString())).ToString();

txtUpdateSubmitterResponse.Text =

client.UploadString(uri, "PUT", data.ToString());

}

}


{

txtUpdateSubmitterResponse.Text = "Exception : " +

ex.Message;

}

}

protected void btnGetSubmitter_Click(object sender, EventArgs e)




{

txtGetSubmitterResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/submitters/{1}",

serviceURL, txtGetSubmitterId.Text);


{



txtAgent.Text;

txtGetSubmitterResponse.Text =

client.DownloadString(uri);

}

}


{

txtGetSubmitterResponse.Text = "Exception : " + ex.Message;

}

}

protected void btnGetCampaignMeta_Click(object sender, EventArgs e)

{

txtGetCampaignMetaResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/campaigns/{1}",

serviceURL, txtGetCampaignMeta.Text);


{



txtAgent.Text;

txtGetCampaignMetaResponse.Text =


}

}





{

txtGetCampaignMetaResponse.Text = "Exception : " +

ex.Message;

}

}

protected void btnGetCampaigns_Click(object sender, EventArgs e)

{

txtGetCampaignsResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/campaigns", serviceURL);

if (!string.IsNullOrEmpty(txtCampModifier.Text))

{

uri = uri + "?" + txtCampModifier.Text;

}


{



txtAgent.Text;

txtGetCampaignsResponse.Text =


}

}


{

txtGetCampaignsResponse.Text = "Exception : " + ex.Message;

}

}

protected void btnRelated_Click(object sender, EventArgs e)

{

txtRelatedContentsResponse.Text = string.Empty;

try

{

string uri = string.Format("{0}/SM2/contents/related/{1}",

serviceURL, txtRelatedContentId.Text);





{



txtAgent.Text;

txtRelatedContentsResponse.Text =


}

}


{

txtRelatedContentsResponse.Text = "Exception : " +

ex.Message;

}

}

}

5.2 Sample Web Application for Eresource Service.

There is a prototype web application for test of eResource Service at:

https://opendata-stg.nlb.gov.sg/openwebsampleapp/

5.3 Other Programming Languages.

Not available at this moment.

Note:

Please email [email protected] with link to your source if you wish to share your

sample implementation codes in other programming languages.

https://opendata-stg.nlb.gov.sg/openwebsampleapp/

mailto:[email protected]

nlb open web service functional design specifications€¦ · 1.30 li lingxia 19 apr 2013 for...

Documents