- What is a Web service?
- What is the "WorldShare Platform"?
- How do Web services add value for my patrons?
- How do Web services save time for my staff?
- What else can I do with Web services?
- Where can I learn more?
OCLC Web Services
Accounts and Authentication
- How do I request a WSKey?
- How do I enable API access?
- How do I get a WorldCat Account?
- How do I reset my WorldCat password?
- What is a WSKey?
- Why am I getting "unknown error" or "bad request" when I try to request a WSKey?
- How do I view my WSKeys and their parameters?
- Can I access multiple institutions from one WSKey?
- How do I add OCLC Services to my key?
- How do I authenticate?
- Are there client side libraries to handle authentication?
- What languages are supported with client side authentication libraries?
- How do I authenticate with mobile devices?
A Web service is a mechanism to make a request of a remote system over the Web. Web services expose structured data - like MARC or XML - across systems, in real time. Facebook, Twitter, Google and Amazon offer web services for their services.
The WorldShare Platform has characteristics common to popular software platforms you may be familiar with like Facebook, Twitter, Google and others. It's an environment that includes tools to Develop applications a Gallery, where libraries can find applications they want to use, and a place for Collaboration where creators, consumers, and the curious can share their common interests. Learn more about the WorldShare Platform.
Web services help you meet your users where they are. You can add more data and functionality to your existing user interfaces. For example, if the local copy of a book is out, you could provide a link to holdings in area libraries using the WorldCat Search API. Web Services also allow a commercial partner such as RedLaser to integrated your libraries holdings into their application, making you easier for your patrons to find!
Because you can combine data in real time, you make it easier for staff do more within their existing workflows. For example, instead of having to have multiple tabs or windows open to see information in WMS, Amazon and a campus financial system; web services could be used to combine information from these different systems into a single interface.
I'm glad you asked! Really, there's a huge variety of potential uses. Take some time to browse through Gallery for inspiration.
Our Pre-requisites Page will give you an idea of what kind of programming skills are involved in using Web services. From there, you can explore our documentation to get started:
The OCLC Developer Network Github Account offers client side libraries that assist with authentication.
You can also Contact Us with questions at firstname.lastname@example.org.
We set limits on API usage that meet our typical member's needs while insuring sufficient network and server resources are available for everyone. For example, the WorldCat Search API has a rolling 24 hour limit of 50,000 requests.
If usage limits are not sufficient for your use case, please e-mail your WSKey (but not your secret) and the API in question to email@example.com along with your expected need.
How do I request a WSKey?
WSKey requests can be made from WSKey Management. For "Sandbox" or trial access, choose the "Production" as the Environment dropdown. Then choose the desired services. Include the phrase "Requesting Sandbox Access" in the "What is the reason for this request?" field. Then submit the request.
How do I enable API access?
- Research the available APIs so you know what to ask for.
- If the API acts on data that is specific to your institution, then you will need to contact your institution's administrator for the following:
- WSKey - clientID and Secret (a public/private key pair)
- principalID - your unique identifier
- principalIDNS - the principalID namespace
- insitutionID(s) - one or more OCLC number assigned to your institution and its branches
- If the API is not institution specific, you can request a personal WorldCat userID and password from worldcat.org (choose "create account" at the top right of the page). You can then request a WSKey from WSKey Management.
How do I get a WorldCat account?
Go to worldcat.org and select "Create an Account" from the top right.
How do I reset my WorldCat password?
Go to worldcat.org, select "Sign In" from the top right and use the "forgot password?" link in the pop-up box.
What is a WSKey?
Web service keys, commonly referred to as WSKeys, are the primary method used for authenticating and authorizing interactions with Web services available on the OCLC WorldShare Platform. WSKeys authenticate clients sending requests to Web services, in effect, creating a “secure pipe” between a remote client and the data and functionality available on the Platform ... read more
Services are attached to WSKeys by OCLC Staff.
Developers may view all the WSKeys assigned to their account, and their parameters, from WSKey Management.
Why am I getting "unknown error" or "bad request" when I try to request a WSKey?
The WSKey request process sometimes returns an "unknown error" or "bad request" error when data is missing in your WorldCat account profile. Check to make sure your WorldCat account has both your first and last name and a valid email address. After signing in to WorldCat.org, click on your name in the upper right hand corner of the screen and then access your member profile and edit your information if necessary. This may not resolve the problem in all cases; please contact us if you see this error after verifying that your information is complete.
How do I get a WSKey that can access a particular institution's data?
When you request a WSKey via WSKey Management make sure you can specify the institution's data you want to get access to via the OCLC Symbol or Registry ID fields in the Request WSkey form. OCLC Staff will verify eligibility and then create a WSKey that has access to that institution's data.
Can I access multiple institutions from one WSKey?
Yes one WSKey can have access to multiple institutions if you are using the Access Token pattern. But only using this pattern. So far, we've only setup WSKeys for commercial partners up this way. Setting a WSKey up this way requires us to have legal agreements which outline that an institution is giving us permission to allow an partner or other institution access to their data.
How do I view my WSKeys and their properties?
Use WSKey Management. Sign in with your WorldCat account and any WSKeys associated with your account will be listed. Clicking on a particular WSKey displays information associated with that key.
How do I add OCLC Services to my key?
Send a request to support at firstname.lastname@example.org which includes a list of the services you are requesting and your WSKey. Please do not send your secret.
How do I authenticate?
WSKeys are used in three patterns to authenticate clients:
- WSKey Lite - the client just passes the WSKey string
- HMAC Signature - the client uses the key and secret to create a signature for their request and passes that signature in an Authorization header
- Access Tokens - the client uses the key to request a time limited token for making requests against specific services.
Are there client side libraries to handle authentication?
OCLC has added client libraries on our GitHub account, https://github.com/oclc-developer-network.
As of March, 2014 we support:
Server Side Authentication (applies generally to OCLC APIs)
- PHP Authentication Library
- Ruby Gem Authentication Library
- A python library is under construction and should be available in March, 2014.
Mobile Authentication (WMS NCIP Patron Profile use case)
What languages are supported with client side authentication libraries?
As of March 2014, libraries for PHP, Ruby, iOS (Objective-C) and Android (Java) are available from our GitHub account, https://github.com/oclc-developer-network
No. HMAC Authentication (a.k.a. URL signing) requires hashing with your Public Key and your Secret. However, the secret must never be sent to the client side or it will be compromised.
Client side calls to APIs should use Access Tokens instead.
How do I authenticate with mobile devices?
Mobile devices can use Access Tokens to make API calls.
Or the WMS NCIP Patron Profile use case, we have created two mobile authentication examples written in native code:
What formats are supported for the data returned by the APIs?
The data returned is API specific so you'll have to see the API's documentation page. However, most APIs work with XML or JSON.
Where can I download MARConvert?
MARConvert can be retrieved from the a repository within the Developer Network GitHub account located https://github.com/OCLC-Developer-Network/MARCView-Convert. Please note, while OCLC is hosting the software, it was not developed by OCLC and we do not provide support for it.