/configuration Get Open Library API configuration
Example request
cURL
curl -X GET "$PLAS_BASE_URL/configuration?version=0.6.7" \
-H 'Accept: application/json' \
-H "Authorization: Bearer $PLAS_TOKEN"JavaScript
const response = await fetch(`${process.env.PLAS_BASE_URL}/configuration?version=0.6.7`, {
method: "GET",
headers: {
"Accept": "application/json",
"Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
},
});
const data = await response.json();Python
import os
import requests
response = requests.get(
f"{os.environ['PLAS_BASE_URL']}/configuration",
params={
"version": "0.6.7",
},
headers={
"Accept": "application/json",
"Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
},
)
data = response.json()PLAS_BASE_URL the provider’s base URL · PLAS_TOKEN an access token.
Parameters
Shared across operations: version. See the shared contract on the version page.Responses
200 Success ConfigurationResponseBody
Example
{
"circulation": {
"checkin": {
"isEnabled": true,
"offline": {
"isAllowed": true
}
},
"checkout": {
"isEnabled": true,
"offline": {
"defaultLoanPeriodDays": 28,
"isAllowed": true
}
},
"securityTags": {
"isDisabled": false
}
},
"content": {
"api": {
"delegated": {
"url": "https://nordby.bibliotek.example/url"
}
},
"uiLanguages": {
"default": "nob",
"supported": [
"nob"
]
}
},
"events": {
"receiver": "https://app.nordby.bibliotek.example/events"
},
"holding": {
"periodical": {
"groupOrdering": [
"year"
]
}
},
"patron": {
"credentials": {
"changeable": [
"password"
],
"resettable": [
"password"
]
},
"deletion": {
"identifierTypes": [
"local"
],
"identityProviders": [
"norway_id_portal"
]
},
"fields": [
{
"field": "emails",
"maxNumberOfEmailAddresses": 3,
"verification": "no_verification"
}
],
"loanHistory": {
"blockManuallyAddingLoans": false
},
"login": {
"allowWithoutCredential": false,
"credentials": [
"password"
],
"identifierTypes": [
"local"
],
"identityProviders": [
"norway_id_portal"
]
},
"registration": {
"identifierTypes": [
"local"
],
"identityProviders": [
"norway_id_portal"
]
}
},
"payment": {
"initialize": {
"state": "do_not_use_initialize"
},
"methods": [
{
"type": "mobile_pay"
}
],
"partial": false
},
"search": {
"api": {
"delegated": {
"url": "https://nordby.bibliotek.example/url"
}
},
"expression": {
"clustering": [
[
{
"type": "mediaTypes"
},
{
"type": "language"
},
{
"codes": [
"trl"
],
"type": "creatorsAndContributors"
},
{
"codes": [
"nrt"
],
"type": "creatorsAndContributors"
}
]
]
},
"suggestions": {
"available": [
{
"description": "Only suggest titles for children.",
"type": "plas.audience.literal"
}
],
"disabled": false
},
"uiLanguages": {
"default": "nob",
"supported": [
"nob"
]
},
"workSearch": {
"facet": {
"available": [
{
"description": "Group the results by media type.",
"type": "plas.audience.literal"
}
]
},
"filter": {
"available": [
{
"description": "Only show works available at the chosen branch.",
"type": "plas.audience.literal"
}
]
},
"sorting": {
"available": [
{
"description": "Newest publications first.",
"type": "plas.relevance.asc"
}
]
}
}
},
"version": "1.0",
"mainBranch": "nordby-main"
}Schema
- circulationConfigurationCirculation
What the provider supports on POST /checkout/{itemId} and POST /checkin/{itemId}.
If this field is missing, the provider supports neither endpoint. A vendor must find
isEnabledset to true here before it checks anything out or in.Show 3 fieldsHide 3 fields
- checkinobject
Whether the provider supports POST /checkin/{itemId}. If this field is missing, it does not.
Show 2 fieldsHide 2 fields
- isEnabledbooleanrequired
True when the provider supports POST /checkin/{itemId}.
When this is false the endpoint is not available, and the rest of this object is ignored.
- offlineobject
Whether the provider accepts a checkin that was already carried out while the vendor was offline, see
checkin.offlineon the request. If this field is missing, it does not.
- checkoutobject
Whether the provider supports POST /checkout/{itemId}. If this field is missing, it does not.
Show 2 fieldsHide 2 fields
- isEnabledbooleanrequired
True when the provider supports POST /checkout/{itemId}.
When this is false the endpoint is not available, and the rest of this object is ignored.
- offlineobject
Whether the provider accepts a checkout that was already carried out while the vendor was offline, see
checkout.offlineon the request. If this field is missing, it does not.
- securityTagsobject
Whether the library uses the security tags in its items, the magnetic strip or RFID chip that makes the gate at the door sound when an item that is not checked out passes through.
This is one decision for the whole library, which is why it is here and not in each checkout or checkin answer. Some libraries never switch the alarm on, or have no gate, and do not want tags armed.
If this field is missing, the library uses security tags.
Show 1 fieldHide 1 field
- isDisabledbooleanrequired
True when the library does not use security tags, so a vendor should not arm them at checkin.
False is the same as the field being missing: tags are used.
- contentConfigurationContentWithApi
Show 2 fieldsHide 2 fields
Show 1 fieldHide 1 field
- delegatedobject
- uiLanguagesobject
This contains the ui language settings.
All ui language codes should be on this list https://www.loc.gov/marc/languages/
Show 2 fieldsHide 2 fields
- defaultstring
This is the default ui language used if no language is added to the requests.
- supportedarray of string
These are the supported ui languages that can be added to the requests.
- eventsobject
events contain configuration data for events in the LMS.
This covers notifications sent to the user and consent changes.Show 1 fieldHide 1 field
- receiverstring
- holdingConfigurationHolding
Show 1 fieldHide 1 field
- periodicalConfigurationHoldingPeriodical
Show 1 fieldHide 1 field
- groupOrderingarray of string
The default ordering of periodical group types is
year,volumeandnumber, orlevel1, ...,level7. It is strongly discouraged to ever mix the named types and the level* types, but if for some reason another group type order is needed,groupOrderingcan be used to tell the vendor the ordering of periodicals.One of: year · volume · number · level1 · level2 · level3 · level4 · level5 · level6 · level7
- patronConfigurationPatron
Show 6 fieldsHide 6 fields
- credentialsobject
This tells what a patron can do with the credentials they use to authenticate.
Not all providers have both a password and a pin code, and a provider that has one may still not let the patron change it. If this is missing, it is unknown, and the vendor should offer neither changing nor resetting a credential.
Show 2 fieldsHide 2 fields
- changeablearray of string
The credentials a patron can change through POST /patron/{patronId}/credential/change. The empty array means that no credential can be changed.
One of: password · pin
- resettablearray of string
The credentials a patron can have reset through POST /patron/credential/reset. The empty array means that no credential can be reset.
One of: password · pin
- deletionobject
Show 2 fieldsHide 2 fields
- identifierTypesarray of PatronIdentifierType
The patron identifier types that can be used to identify the patron in POST /patron/delete.
If this is missing, the provider only accepts identifiers without a
type, meaning an identifier whose type is unknown.One of: local · email · phone · norway_national_library_card · norway_national_birth_number · denmark_cpr
- identityProvidersarray of string
An array of enabled identity provider types that can be used for patron deletion.
One of: norway_id_portal · norway_nl_oidc · norway_feide_oidc · denmark_mit_id · denmark_dbc_access_platform
This contributes with further information about some of the patron fields, like if they are updatable or not, how they are constructed and their limitations.
The array should at most contain one element of each type.
Show 3 variantsHide 3 variants
Selected by the field field
- loanHistoryobject
Show 1 fieldHide 1 field
- blockManuallyAddingLoansboolean
If this is true, it is expected that patrons are not allowed to manually add loans to the loan history. The default is false.
- loginobject
Show 4 fieldsHide 4 fields
- allowWithoutCredentialboolean
If this is true, a patron can be authenticated by identifier alone through POST /patron/authentication/no-password. The default is false.
- credentialsarray of string
The credentials a patron can authenticate with through POST /patron/authentication.
This is what the
passwordfield of that request body actually carries, so it is also what the vendor should ask the patron for and label the input as. A provider that only has pin codes lists onlypin, even though the field on the wire is still calledpassword.If this is missing, it is unknown, and the vendor should assume a password.
One of: password · pin
- identifierTypesarray of PatronIdentifierType
The patron identifier types that can be used to authenticate, through POST /patron/authentication and POST /patron/authentication/no-password.
These are also the types POST /patron/credential/reset accepts, since it is the recovery path for login.
If this is missing, the provider only accepts identifiers without a
type, meaning an identifier whose type is unknown.One of: local · email · phone · norway_national_library_card · norway_national_birth_number · denmark_cpr
- identityProvidersarray of string
An array of enabled identity provider types for patron login.
One of: norway_id_portal · norway_nl_oidc · norway_feide_oidc · denmark_mit_id · denmark_dbc_access_platform
- registrationobject
Show 2 fieldsHide 2 fields
- identifierTypesarray of PatronIdentifierType
The patron identifier types that can be used to register a patron, through POST /patron/registration and POST /patron/registration/possible.
If this is missing, the provider only accepts identifiers without a
type, meaning an identifier whose type is unknown.One of: local · email · phone · norway_national_library_card · norway_national_birth_number · denmark_cpr
- identityProvidersarray of string
An array of enabled identity provider types that can be used for patron registration.
One of: norway_id_portal · norway_nl_oidc · norway_feide_oidc · denmark_mit_id · denmark_dbc_access_platform
- paymentConfigurationPayment
If this field is missing, the vendor does not support payments.
Show 3 fieldsHide 3 fields
- initializeobject
Show 1 fieldHide 1 field
- statestring
This tells if the vendor should use the payment initialize endpoint or not.
The two possible states are:
do_not_use_initialize, This means that the vendor should not use the initialize endpoint when starting a payment.use_initialize, This means that the vendor should always use the initialize endpoint when starting a payment.
If no state is mentioned, the default state is
use_initialize.One of: do_not_use_initialize · use_initialize
This is a list of the payment methods that the vendor supports.
If this is missing, there are no payment methods available.
Show 1 fieldHide 1 field
- typestring
This represents the payment method type.
One of: mobile_pay · vipps ·
- partialboolean
If this is true, the provider allows partial payments. Default is false.
Show 5 fieldsHide 5 fields
Show 1 fieldHide 1 field
- delegatedobject
- expressionConfigurationSearchExpression
Show 1 fieldHide 1 field
This is the providers preferred clustering of publications.
This clustering can be used to group publications together, emulating an expression level.
- suggestionsConfigurationSearchSuggestions
Show 2 fieldsHide 2 fields
This tells which filters are available for the
/suggestionsendpoint.See ConfigurationSearchSuggestionsFilterAvailable in the schema index
- disabledboolean
This tells the Vendor if the
/suggestionsendpoint is disabled or not. (Defaultfalse).If this is set to
true, the Vendor should not make request to the/suggestionsendpoint.
- uiLanguagesobject
This contains the ui language settings.
All ui language codes should be on this list https://www.loc.gov/marc/languages/
Show 2 fieldsHide 2 fields
- defaultstring
This is the default ui language used if no language is added to the requests.
- supportedarray of string
These are the supported ui languages that can be added to the requests.
- workSearchobject
- versionstringrequired
This contains the version of the Open Library API.
- mainBranchunknownrequirednot declared in the specification
400 The list of errors. Errors
Shared response, defined once for the whole API. See the shared contract on the version page.
Example
{
"errors": [
{
"code": 200103,
"info": "200103: invalid/unsupported query parameter value"
}
]
}Schema
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
A number representing the type of error.
List of error codes:
- \<error code\>: \<error description\>
- 500: System error
- 600: Unsupported Open Library API version
- 10001: Endpoint disabled
- 71001: Consent has not been given for 'loan history'
- 100001: Wrong patron identifier, password or pin code
- 100011: New password or pin code rejected, because it does not meet the provider's requirements
- 100013: The provider does not let the patron change the given credential
- 100023: Patron ID not found
- 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
- 100211: maxNumberOfEmailAddresses exceeded
- 100215: maxNumberOfPhoneNumbers exceeded
- 100221: Pickup location cannot contain sections
- 100411: Updating patron consent failed
- 100611: Updating patron notification settings failed
- 101001: Reservation ID not found
- 101047: Branch ID cannot be used as pick up branch
- 101053: Section ID cannot be used as pick up branch
- 102001: Loan ID not found
- 102301: Loan not renewable, because it is an interlibrary loan
- 102311: Loan not renewable, because it is reserved
- 110001: Branch ID not found
- 200001: Publication ID not found
- 200077: ui language not supported
- 200101: missing required query parameter
- 200103: invalid/unsupported query parameter value
- 300001: Initialize payment should not be used
- 300005: Initialize payment should be used
- 300009: Payment method not supported
- 300013: Payment method does not support partial payment
- 300301: Finalized payment can not de changed
- 300311: FinalizePaymentRequest.fees contains fees with the same ID
- 310001: Loan history ID not found
- 310011: Loan history ID already exists
- 330001: List ID not found
- 330011: List ID already exists
- 330101: List item ID not found
- 330111: List item ID already exists
One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
Starts with the text matching the error code field (defined above), and a describing text could be added.
401 Bearer token invalid, missing, or expired.
Shared response, defined once for the whole API. See the shared contract on the version page.
No response body.