Integration library systems
This page describes available API endpoints for library systems that want to integrate with the e-library system for allbok. All APIs are server-to-server APIs and it is the integrator’s responsibility to ensure safekeeping of credentials and to ensure that users only get access to data from it own libraries.
More API endpoints will be added here as we are gathering feedback from integrators.
Environment information
You need an access token to access the API endpoints as described under Authentication and pass this in the Authorization header on all requests. The token must be created with the scope given below (depending on environment):
Environment | Required scope | Base URL for API calls |
|---|---|---|
Production | https://allbok.api.boknett.cloud/library_integrators | https://allbok.api.boknett.cloud |
Test | https://allbok.api.stage.boknett.cloud/library_integrators | https://allbok.api.stage.boknett.cloud |
API endpoints
Metadata search
The metadata search endpoint provides advanced query features to search in the metadata catalogue for e-/audio books. The API backend is an AWC CloudSearch search domain, and using the API requires some knowledge of the query language used by CloudSearch. We recommend reading AWS' documentation on searching CloudSearch, relevant documentation is also linked directly in the table below. The response from the API is our custom format, so there is not need to look into the response format from CloudSearch, but the parameters you send in are passed directly to CloudSearch (with some limitations documented below).
POST /metadata/query
Content-type: application/json
JSON attributes in request body
Attribute name | Required? | Data type | Description |
|---|---|---|---|
lender_ids | Yes | array | List of library IDs that the user has access to |
query.q | No | string |
|
query.parser | Yes | “structured” or “simple” | Depending on the type of query being done, see documentation for details. Only structured and simple is supported. |
query.sort | No | string | Sort result, see documentation for details. |
query.fq | No | string | Filtering the search result without affecting relevant. Documentation. |
query.size | No | int | Number of books returned per page, max page size is 100. |
query.start | No | int | Paging parameter, read documentation for details. |
query.cursor | No | string | Paging parameter, read documentation for details. |
Available fields used in query.fq, query.sort and query.q
Field name | CloudSearch data type | Description |
|---|---|---|
actors | literal-array | Name of all actors expect authors registered on book |
actor_roles | literal-array | Roles on the actors in the “actors” field, will always have same length as “actors”. Use corresponding key value to find which actor the role is for |
actors_text | text-array | Copy of actors data, just used for text searching in actor names |
alternative_editions_eans | text-array | List of ISBNs for related editions e.g hard cover, audio book etc |
authors | literal-array | Name of all authors |
authors_text | text-array | Copy of “authors” just used for text searching in author name |
bokbasen_subjects | literal-subject | Bokbasen subject terms |
ean | text | EAN (ISBN13) for the book, ean is also used as ID |
edition | int | Edition number |
edition_note | text | Note related to the edition |
file_format | literal | EPUB, PDF, MP3 (for all audio books), or EBP |
languages | literal-array | Language given as an array of ISO 639-2-B codes |
note | text |
|
pages | int | Number of pages in print edition |
product_owner | literal | Legal name of the owner |
product_owner_id | literal | Bokbasen id of the legal owner of the book (vareeier) |
published_year | int | Year of publication |
publishers | literal-array | List of names of publishers |
publishers_description | text | Description of the book, provided by the publisher |
replaced_by_ean | literal | If the book is replaced by another book, ean of the new title is here |
series_titles | literal-array | Name of series that the book is a part of |
series_id | literal-array | Identifiers for each series, if serie does not have an id yet, 0 is given. |
thema_edu_no | literal-array | Thema educational purpose qualifiers (text description in Norwegian) |
thema_geo_no | literal-array | Thema geography qualifiser (text description in Norwegian) |
thema_interest_no | literal-array | Thema interest qualifiers (text description in Norwegian) |
thema_lang_no | literal-array | Thema language qualifiers (text description in Norwegian) |
thema_style_no | literal-array | Thema style qualifiers (text description in Norwegian) |
thema_subject_codes | literal-array | |
thema_subject_no | literal-array | Thema subject codes (Norwegian text) |
thema_time_no | literal-array | Thema time qualifiers (text description in Norwegian) |
title | text | Title of the book (a concatenated title including sub titles) |
_score | double | CloudSearch’s relevance score |
Response attributes
The response data model does not 100% align with the flat data structure required by a search engine like CloudSearch. The response has a clearer data model with complex objects used where appropriate.
Example queries
Simple search for the term “mord” automatically searched in all text fields including title, subjects and description.
{
"lender_ids": ["614200"],
"query": {
"q": "mord",
"parser": "simple",
"size": 100,
"cursor": "initial"
}
}
Run same search again (“mord”), but this time filter on language, only getting books in “bokmål”.
{
"lender_ids": ["614200"],
"query": {
"q": "mord",
"parser": "simple",
"size": 100,
"fq": "(and languages:'bm')",
"cursor": "initial"
}
}
Structured query filtering on title, author and year
{
"lender_ids": ["614200"],
"query": {
"q": "(and title:'Snømannen' published_year:2011 authors:'Nesbø, Jo')",
"parser": "structured",
"size": 100,
"cursor": "initial"
}
}