Advanced Usage
OCLC Number Formatting
MetadataSession accepts OCLC numbers in methods' arguments as integers or strings. OCLC numbers will be parsed with or without a prefix (eg. "(OCoLC)", "ocm", "ocn", or "on") to ensure they correspond to OCLC's formatting rules for OCLC control numbers. The following are all acceptable:
session.brief_bibs_get(oclcNumber="ocm00012345")
session.brief_bibs_search(oclcNumber="00054321")
session.bib_get_classification(oclcNumber=12121)
session.brief_bibs_search(oclcNumber="(OCoLC)00054321")
bib_get_current_oclc_number and holdings_get_current methods accept multiple OCLC Numbers passed to the oclcNumbers argument. For these methods OCLC Numbers can be passed as a list of strings and/or integers or a string with the numbers separated by commas. The oclcNumbers argument will also accept a single integer as a valid arguement. The following are all acceptable:
session.holdings_get_current(oclcNumbers=["ocm00012345", "00012346", "12347"])
session.holdings_get_current(oclcNumbers=["ocm00012345", "00012346", 12347])
session.bib_get_current_oclc_number(oclcNumbers="ocm00012345, 00012346, 12347")
session.bib_get_current_oclc_number(oclcNumbers=12347)
Authentication
WorldcatAccessToken
A WorldcatAccessToken object retains the underlying Requests object functionality (requests.Request) which can be accessed via the .server_response attribute:
from bookops_worldcat import WorldcatAccessToken
token = WorldcatAccessToken(
key="my_WSKey",
secret="my_secret",
scopes="WorldCatMetadataAPI",
agent="my_app/version 1.0.0"
)
print(token.server_response.status_code)
#>200
print(token.server_response.elapsed):
#>0:00:00.650108
.json() method.
{
"access_token": "tk_TokenString",
"expires_at": "2024-03-14 19:52:37Z",
"authenticating_institution_id": "00001",
"principalID": "",
"context_institution_id": "00001",
"scopes": "WorldCatMetadataAPI:view_brief_bib",
"token_type": "bearer",
"expires_in": 1199,
"principalIDNS": ""
}
is_expired method:
print(token.is_expired())
#>False
WorldcatAuthorizationError which provides the error code and detailed message returned by the server.
from bookops_worldcat import WorldcatAccessToken
token = WorldcatAccessToken(
key="my_WSKey",
secret="my_secret",
scopes="MetadataAPI",
agent="my_app/version 1.0.0"
)
print(token)
#>bookops_worldcat.errors.WorldcatAuthorizationError: b'{"code":403,"message":"Invalid scope(s): MetadataAPI (MetadataAPI) [Invalid service specified, Not on key]"}'
Identifying your institution
Though uncommon, users can request that OCLC set up their WSKeys to allow them to work on behalf of multiple institutions. The user can then authenticate on behalf of any of the institutions associated with that WSKey.
If your WSKey is set up to work on behalf of multiple institutions, you can identify your institution when initiating a WorldcatAccessToken object. Pass the Registry ID for the institution you wish to work on behalf of to the scopes parameter as context.
token = WorldcatAccessToken(
key="my_WSKey",
secret="my_secret",
scopes="WorldCatMetadataAPI context:00001",
agent="my_app/1.0.0"
)
MetadataSession
Event hooks
MetadataSession methods support Requests event hooks which can be passed as an argument:
def print_url(response, *args, **kwargs):
print(response.url)
hooks = {'response': print_url}
session.brief_bibs_get(850939579, hooks=hooks)
#>https://metadata.api.oclc.org/worldcat/search/brief-bibs/850939579
Identifying your application
BookOps-Worldcat provides a default user-agent value in the headers of all requests to OCLC web services: bookops-worldcat/{version}. Users are encouraged to update the user-agent value to properly identify your application to OCLC servers. This will provide a useful piece of information for OCLC staff if they need to assist with any troubleshooting problems that may arise.
To set a custom user-agent in a session simply pass it as an argument when initiating the session:
session = MetadataSession(authorization=token, agent="my_client_name")
Alternatively, users can update the .headers attribute after initializing the session:
session.headers.update({"user-agent": "my-app/version 1.0"})
The user-agent header can be set for an access token request as well. To do that simply pass it as the agent parameter when initiating WorldcatAccessToken object:
token = WorldcatAccessToken(
key="my_WSKey",
secret="my_secret",
scopes="WorldCatMetadataAPI",
agent="my_app/1.0.0"
)
Automatic Token Refresh
All requests made within a MetadataSession have a built-in access token auto-refresh feature. While a session is open, the current token will be checked for expiration before sending a request. If the token has expired, a new token will be obtained and the MetadataSession will continue to send requests.
Retry Failed Requests
Users can configure a MetadataSession to automatically retry failed requests. This functionality is customizable with the totalRetries, backoffFactor, statusForcelist, and allowedMethods arguments.
Note
It is recommended that users only allow for automatic retries on timeouts or other server errors. Users should also keep their automatic retries as low as possible in order to not overburden the web service. Users should not set up automatic retries for authentication (401, 403) or malformed request errors (400).
with MetadataSession(
authorization=token,
totalRetries=3,
backoffFactor=0.1,
statusForcelist=[500, 502, 503, 504],
allowedMethods=["GET"],
) as session:
session.bib_get("12334")
RetryError if a request is attempted up to the value of totalRetries and still fails.