Configuration

View as Markdown The page’s .md file llms.txt All pages, for AI tools Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

No description in the specification.

3 operations

GET /configuration

Get Open Library API configuration

Bearer token GetConfiguration

Example request

cURL

curl -X GET "$PLAS_BASE_URL/configuration?version=0.6.3" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN"

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/configuration?version=0.6.3`, {
  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.3",
    },
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
)
data = response.json()

The host and token are environment variables: 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

Generated from the schema

Example

{
  "events": {
    "receiver": "https://app.nordby.bibliotek.example/events"
  },
  "holding": {
    "periodical": {
      "groupOrdering": [
        "year"
      ]
    }
  },
  "patron": {
    "fields": [
      {
        "field": "emails",
        "maxNumberOfEmailAddresses": 3,
        "verification": "no_verification"
      }
    ],
    "identifierTypes": [
      {
        "type": "norway_birth_number"
      }
    ],
    "identityProviders": [
      {
        "type": "norway_min_id"
      }
    ],
    "loanHistory": {
      "blockManuallyAddingLoans": false
    },
    "login": {
      "identityProviders": [
        "bankid"
      ]
    },
    "registration": {
      "identifierTypes": [
        "norway_birth_number"
      ],
      "identityProviders": [
        "bankid"
      ]
    }
  },
  "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": "0.6.3"
}

Schema

ConfigurationResponseBody

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, volume and number, or level1, ..., 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, groupOrdering can 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
- fieldsarray of ConfigurationPatronField
  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
  Variant: emails
  ConfigurationPatronFieldEmails
  See ConfigurationPatronFieldEmails in the schema index
  Variant: phoneNumbers
  ConfigurationPatronFieldPhoneNumbers
  See ConfigurationPatronFieldPhoneNumbers in the schema index
  Variant: pickupLocation
  ConfigurationPatronFieldPickupLocation
  See ConfigurationPatronFieldPickupLocation in the schema index
- identifierTypesarray of object
  This is an array of the patron identifier types that the vendor supports.
  If this is missing, only the empty identifier type is supported.
  The empty identifier type is when no identifier type is specified, and it is assumed to be unknown.
  Show 1 fieldHide 1 field
  - typestring
    One of: norway_birth_number · denmark_cpr
- identityProvidersarray of object
  Show 1 fieldHide 1 field
  - typestring
    One of: norway_min_id · norway_id_portal · denmark_mit_id
- 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 1 fieldHide 1 field
  - identityProvidersarray of string
    An array of enabled identity provider types for patron login.
- registrationobject
  Show 2 fieldsHide 2 fields
  - identifierTypesarray of string
    An array of enabled user identifier types for patron registration.
    One of: norway_birth_number · denmark_cpr
  - identityProvidersarray of string
    An array of enabled identity provider types that can be used for patron registration.
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
- methodsarray of ConfigurationPaymentMethod
  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.
searchConfigurationSearchWithApi
Show 5 fieldsHide 5 fields
- apiConfigurationSearchApi
  Show 1 fieldHide 1 field
  - delegatedobject
- expressionConfigurationSearchExpression
  Show 1 fieldHide 1 field
  - clusteringarray of array of ExpressionClusteringField
    This is the providers preferred clustering of publications.
    This clustering can be used to group publications together, emulating an expression level.
    See ExpressionClusteringField in the schema index
- suggestionsConfigurationSearchSuggestions
  Show 2 fieldsHide 2 fields
  - availablearray of ConfigurationSearchSuggestionsFilterAvailable
    This tells which filters are available for the /suggestions endpoint.
    See ConfigurationSearchSuggestionsFilterAvailable in the schema index
  - disabledboolean
    This tells the Vendor if the /suggestions endpoint is disabled or not. (Default false).
    If this is set to true, the Vendor should not make request to the /suggestions endpoint.
- 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
  Show 3 fieldsHide 3 fields
versionstringrequired
This contains the version of the Open Library API.

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
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 username or password
  - 100023: Patron ID not found
  - 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 · 100001 · 100023 · 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.

POST /configuration/event/register/receiver

Register an event receiver

Bearer token RegisterEventReceiver

Example request

cURL

curl -X POST "$PLAS_BASE_URL/configuration/event/register/receiver?version=0.6.3" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN" \
  -d '{
  "secret": "Qm8x2Lp7Vn4Kt9Rs",
  "url": "https://nordby.bibliotek.example/events/84410"
}'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/configuration/event/register/receiver?version=0.6.3`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
  body: JSON.stringify({
    "secret": "Qm8x2Lp7Vn4Kt9Rs",
    "url": "https://nordby.bibliotek.example/events/84410"
  }),
});

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/configuration/event/register/receiver",
    params={
        "version": "0.6.3",
    },
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
    json={
        "secret": "Qm8x2Lp7Vn4Kt9Rs",
        "url": "https://nordby.bibliotek.example/events/84410",
    },
)
response.raise_for_status()

The host and token are environment variables: 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.

Request body

application/json · required · RegisterEventReceiverRequestBody

secretstringrequiredmin length 16
This cannot be empty. It should be randomly generated, and should be used to validate the Provider in the Vendor API.
urlstringrequired
The empty string will unregister an existing receiver for the vendor.

Responses

204 Success

No response body.

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
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 username or password
  - 100023: Patron ID not found
  - 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 · 100001 · 100023 · 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.

GET /configuration/search

Get search configuration

Bearer token GetSearchConfiguration

Example request

cURL

curl -X GET "$PLAS_BASE_URL/configuration/search?version=0.6.3" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN"

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/configuration/search?version=0.6.3`, {
  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/search",
    params={
        "version": "0.6.3",
    },
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
)
data = response.json()

The host and token are environment variables: 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 ConfigurationSearchResponseBody

Generated from the schema

Example

{
  "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"
        }
      ]
    }
  }
}

Schema

ConfigurationSearchResponseBody

expressionConfigurationSearchExpression
Show 1 fieldHide 1 field
- clusteringarray of array of ExpressionClusteringField
  This is the providers preferred clustering of publications.
  This clustering can be used to group publications together, emulating an expression level.
  Show 5 variantsHide 5 variants
  Selected by the field type
  Variant: creators
  ExpressionClusteringFieldNamedCreators
  See ExpressionClusteringFieldNamedCreators in the schema index
  Variant: contributors
  ExpressionClusteringFieldNamedContributors
  See ExpressionClusteringFieldNamedContributors in the schema index
  Variant: creatorsAndContributors
  ExpressionClusteringFieldNamedCreatorsAndContributors
  See ExpressionClusteringFieldNamedCreatorsAndContributors in the schema index
  Variant: mediaTypes
  ExpressionClusteringFieldNamedMediaTypes
  See ExpressionClusteringFieldNamedMediaTypes in the schema index
  Variant: language
  ExpressionClusteringFieldNamedLanguage
  See ExpressionClusteringFieldNamedLanguage in the schema index
suggestionsConfigurationSearchSuggestions
Show 2 fieldsHide 2 fields
- availablearray of ConfigurationSearchSuggestionsFilterAvailable
  This tells which filters are available for the /suggestions endpoint.
  Show 2 fieldsHide 2 fields
  - descriptionstring
    This is a description of what type of filter this is.
  - typeSuggestionsFilterTyperequired
    Filter type, this is the value given to the suggestions filter parameter.
    One of: plas.audience.literal · plas.audience.ageRange · plas.audience.ageGroup · plas.mediaTypes · plas.language · plas.subjects · plas.genres · plas.forms
    See SuggestionsFilterType in the schema index
- disabledboolean
  This tells the Vendor if the /suggestions endpoint is disabled or not. (Default false).
  If this is set to true, the Vendor should not make request to the /suggestions endpoint.
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
Show 3 fieldsHide 3 fields
- facetConfigurationWorkSearchFacet
  Show 1 fieldHide 1 field
  - availablearray of ConfigurationWorkSearchFacetAvailable
    See ConfigurationWorkSearchFacetAvailable in the schema index
- filterConfigurationWorkSearchFilter
  Show 1 fieldHide 1 field
  - availablearray of ConfigurationWorkSearchFilterAvailable
    See ConfigurationWorkSearchFilterAvailable in the schema index
- sortingConfigurationWorkSearchSorting
  Show 1 fieldHide 1 field
  - availablearray of ConfigurationWorkSearchSortingAvailable
    See ConfigurationWorkSearchSortingAvailable in the schema index

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
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 username or password
  - 100023: Patron ID not found
  - 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 · 100001 · 100023 · 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.