Work

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.

2 operations

GET /work

Get Works

Bearer token GetWorks

Example request

cURL

curl -X GET "$PLAS_BASE_URL/work?work_ids=882107&version=0.6.6" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN"

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/work?work_ids=882107&version=0.6.6`, {
  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']}/work",
    params={
        "work_ids": "882107",
        "version": "0.6.6",
    },
    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

work_idsrequired: query · array of string
A list of work IDs, work IDs should be url encoded and separated by a comma.
That means that, if you have e.g. three work IDs "work-123", "work-456,abcd" and "789101112", they should be sent as: "work_ids=work-123,work-456%2Cabcd,789101112".
Example: 882107

Shared across operations: ui_language, version. See the shared contract on the version page.

Responses

200 Success GetWorksResponseBody

Generated from the schema

Example

{
  "works": {
    "882107": {
      "audience": [
        {
          "code": "SplxlOBeZQQYbYS6WxSbIA",
          "type": "literal",
          "value": "Adults"
        }
      ],
      "classification": [
        {
          "name": "Kari Nordmann",
          "number": "839.8236",
          "type": "dewey"
        }
      ],
      "contributors": [
        {
          "agent": {
            "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
            "fullName": "Sigrid Undset",
            "id": "agent-4102",
            "images": [
              {
                "height": 1200,
                "mime": "png",
                "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                "width": 800,
                "type": "agent"
              }
            ],
            "active": {
              "type": "literal",
              "value": "1882-1949"
            },
            "birthDate": {
              "type": "literal",
              "value": "1920"
            },
            "deathDate": {
              "type": "literal",
              "value": "1920"
            },
            "externals": {
              "identifiers": [
                {
                  "type": "norwegianAuthorityFile",
                  "value": "4102"
                }
              ]
            },
            "givenName": "Kari",
            "surname": "Nordmann",
            "type": "person"
          },
          "roles": [
            {
              "roleCode": "aut",
              "type": "marcRelator"
            }
          ]
        }
      ],
      "creationDate": {
        "type": "literal",
        "value": "1920"
      },
      "creators": [
        {
          "agent": {
            "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
            "fullName": "Sigrid Undset",
            "id": "agent-4102",
            "images": [
              {
                "height": 1200,
                "mime": "png",
                "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                "width": 800,
                "type": "agent"
              }
            ],
            "active": {
              "type": "literal",
              "value": "1882-1949"
            },
            "birthDate": {
              "type": "literal",
              "value": "1920"
            },
            "deathDate": {
              "type": "literal",
              "value": "1920"
            },
            "externals": {
              "identifiers": [
                {
                  "type": "norwegianAuthorityFile",
                  "value": "4102"
                }
              ]
            },
            "givenName": "Kari",
            "surname": "Nordmann",
            "type": "person"
          },
          "roles": [
            {
              "roleCode": "aut",
              "type": "marcRelator"
            }
          ]
        }
      ],
      "description": [
        {
          "type": "literal",
          "value": "A historical novel in three parts, set in 14th-century Norway."
        }
      ],
      "forms": [
        {
          "id": "94549",
          "label": "Novel"
        }
      ],
      "genres": [
        {
          "id": "94549",
          "label": "Historical fiction"
        }
      ],
      "identifier": "882107",
      "images": [
        {
          "height": 1200,
          "mime": "png",
          "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
          "width": 800,
          "type": "frontCover"
        }
      ],
      "language": [
        {
          "code": "SplxlOBeZQQYbYS6WxSbIA",
          "name": "Kari Nordmann"
        }
      ],
      "publicationIds": [
        "41867"
      ],
      "subjects": [
        {
          "id": "94549",
          "label": "Middle Ages"
        }
      ],
      "titles": [
        {
          "language": {
            "code": "SplxlOBeZQQYbYS6WxSbIA",
            "name": "Kari Nordmann"
          },
          "main": "Kristin Lavransdatter",
          "part": {
            "name": "Kari Nordmann",
            "number": "1"
          },
          "remainder": "The Wreath",
          "type": "preferred"
        }
      ]
    }
  }
}

Schema

GetWorksResponseBody

worksmap of Workrequired
Show 1 fieldHide 1 field
- any keyWork
  Show 14 fieldsHide 14 fields
  - audiencearray of Audience
    Intended audience, target audience or intellectual level of the work.
    See WorkAudience in the schema index
  - classificationarray of Classification
    Classification of the work.
    See WorkClassification in the schema index
  - contributorsarray of Contributor
    The contributor(s) to the work.
    See WorkContributors in the schema index
  - creationDateDate
    See Date in the schema index
  - creatorsarray of Contributor
    The creator(s) of the work.
    See WorkCreators in the schema index
  - descriptionarray of Description
    Help readers understand what the work is about and whether they might be interested in lending/reserving it.
    See WorkDescription in the schema index
  - formsarray of Form
    Form is a more specific type of metadata that describes the physical structure or organization of a work.
    See WorkForms in the schema index
  - genresarray of Genre
    Genre is a broad category of works that share similar characteristics, such as style, tone, or subject matter.
    See WorkGenres in the schema index
  - identifierstringrequired
    Work identifier. This is searchable through the GET /work endpoint.
  - imagesarray of ImagePublication
    Images to use with the work.
    See WorkImages in the schema index
  - languagearray of Language
    This is the original language of the work. If the original version of the work uses multi languages this will also contain them.
    See WorkLanguage in the schema index
  - publicationIdsarray of string
    All publication identifiers from the works underlying publications. These are searchable through the GET /publication endpoint.
  - subjectsarray of Subject
    Subject is a topic or theme that is covered in a work.
    See WorkSubjects in the schema index
  - titlesarray of Titlerequiredmin items 1
    Title of the work.
    See WorkTitles 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
  - 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 · 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.

404 Resource not found.

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

No response body.

GET /work/search

Search Works

Bearer token SearchWorks

Search the metadata and returns with a list of works.

It’s expected that the fields that are arrays in the search result are sorted that same way in /work and /publication.

Filters:

plas.audience.literal (work)
plas.audience.ageRange (work)
plas.audience.ageGroup (work)
plas.mediaTypes (publication)
plas.language (work and publication)
plas.subjects (work)
plas.genres (work)
plas.forms (work)
plas.agent (work)

Facets:
All facets should also exist (with the same name) as an filter.

plas.audience.literal
plas.audience.ageRange
plas.audience.ageGroup
plas.mediaTypes
plas.language
plas.subjects
plas.genres
plas.forms
plas.agent

Sorting:

plas.relevance.asc
plas.relevance.desc (default)
plas.titles.asc
plas.titles.desc
plas.publicationDate.asc
plas.publicationDate.desc

Example request

cURL

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

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/work/search?version=0.6.6`, {
  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']}/work/search",
    params={
        "version": "0.6.6",
    },
    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

query: query · string
The search query.
Example: undset
page: query · integer
Page number (default 1).
Example: 1
size: query · integer
Page size (default 10). It's important to be aware that, the page size here is only a preferred page size, the result set can be both small and greater, depending on the implementation from the LMS provider. This is important to consider in any product design.
Example: 10
facet: query · array of SearchFacetType
Return these facets.
Example: plas.audience.literal
facet_terms_size: query · integer
Return this number of facet terms for each requested facet (default 10).
Example: 10
sort: query · SearchSortingType
Sorting
Example: plas.relevance.asc
filter: query · map of string
The individual filter values are OR'ed together, and the filter are then AND'ed together. The hole statement will be AND'ed with the given query.
Eg. filter[plas.mediaTypes]=book,cd&filter[plas.subjects]=dance will be made into plas.mediaTypes=(book OR cd) AND plas.subjects=dance
The possible keys in this map are the filters defined in the /configuration(/search) endpoint (field: (search->)workSearch->filter->available) and are the list of strings of the SearchFilterType type.
Example: {"filter-1":"Example filter"}

Shared across operations: ui_language, version. See the shared contract on the version page.

Responses

200 Success SearchWorksResponseBody

Generated from the schema

Example

{
  "endOfResults": false,
  "facets": [
    {
      "name": "Kari Nordmann",
      "terms": [
        {
          "name": "Kari Nordmann",
          "occurrences": 4,
          "value": "book"
        }
      ],
      "type": "plas.audience.literal"
    }
  ],
  "results": [
    {
      "work": {
        "creationDate": {
          "type": "literal",
          "value": "1920"
        },
        "creators": [
          {
            "agent": {
              "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
              "fullName": "Sigrid Undset",
              "id": "agent-4102",
              "images": [
                {
                  "height": 1200,
                  "mime": "png",
                  "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                  "width": 800,
                  "type": "agent"
                }
              ],
              "active": {
                "type": "literal",
                "value": "1882-1949"
              },
              "birthDate": {
                "type": "literal",
                "value": "1920"
              },
              "deathDate": {
                "type": "literal",
                "value": "1920"
              },
              "externals": {
                "identifiers": [
                  {
                    "type": "norwegianAuthorityFile",
                    "value": "4102"
                  }
                ]
              },
              "givenName": "Kari",
              "surname": "Nordmann",
              "type": "person"
            },
            "roles": [
              {
                "roleCode": "aut",
                "type": "marcRelator"
              }
            ]
          }
        ],
        "forms": [
          {
            "id": "94549",
            "label": "Novel"
          }
        ],
        "identifier": "882107",
        "images": [
          {
            "height": 1200,
            "mime": "png",
            "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
            "width": 800,
            "type": "frontCover"
          }
        ],
        "publications": [
          {
            "identifier": "310552",
            "language": [
              {
                "code": "SplxlOBeZQQYbYS6WxSbIA",
                "name": "Kari Nordmann"
              }
            ],
            "mediaTypes": [
              {
                "code": "book",
                "name": "Kari Nordmann"
              }
            ]
          }
        ],
        "titles": [
          {
            "language": {
              "code": "SplxlOBeZQQYbYS6WxSbIA",
              "name": "Kari Nordmann"
            },
            "main": "Kristin Lavransdatter",
            "part": {
              "name": "Kari Nordmann",
              "number": "1"
            },
            "remainder": "The Wreath",
            "type": "preferred"
          }
        ]
      }
    }
  ],
  "total": 12
}

Schema

SearchWorksResponseBody

endOfResultsbooleanrequired
If this is false, we haven't reached the end of the search result yet, if it's false we have, and if it's missing or null we don't know.
facetsarray of Facet
This array contains the requested facets, and their terms. Each facet type should only appear once in the array.
Show 3 fieldsHide 3 fields
- namestring
  A displayable (human readable) facet name.
- termsarray of FacetTermrequiredmin items 1
  Show 3 fieldsHide 3 fields
  - namestringrequired
    A displayable (human readable) representation of facet term name.
  - occurrencesinteger
    The number of occurrences in the search result, based on works.
  - valuestringrequired
    The facet terms searchable value.
- typeSearchFacetTyperequired
  Facet type, this is the value given to the search facet parameter.
  The SearchFacetType should always exists in SearchFilterType
  One of: plas.audience.literal · plas.audience.ageRange · plas.audience.ageGroup · plas.mediaTypes · plas.language · plas.subjects · plas.genres · plas.forms
  Show 2 variantsHide 2 variants
  Variant: SearchFacetTypeEnum
  SearchFacetTypeEnum
  Variant: SearchFacetTypeLiteral
  SearchFacetTypeLiteral
resultsarray of SearchResultEntryrequired
It's important to be aware that, the result size doesn't always match the given page size, the result set can be both small and greater.
Show 1 fieldHide 1 field
- workSearchResultEntryWorkrequired
  Show 7 fieldsHide 7 fields
  - creationDateDate
    See Date in the schema index
  - creatorsarray of Contributor
    The creator(s) of the work.
    See WorkCreators in the schema index
  - formsarray of Form
    Form is a more specific type of metadata that describes the physical structure or organization of a work.
    See WorkForms in the schema index
  - identifierstringrequired
    Work identifier. This is searchable through the GET /work endpoint.
  - imagesarray of ImagePublication
    Images to use with the work.
    See ImagePublication in the schema index
  - publicationsarray of SearchResultEntryPublicationrequiredmin items 1
    This contain only the underlying publications from the work, that matches the search criteria.
    See SearchResultEntryPublication in the schema index
  - titlesarray of Titlerequiredmin items 1
    Title of the work.
    See WorkTitles in the schema index
totalinteger
The total number of results in the whole search result.

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
  - 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 · 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.

404 Resource not found.

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

No response body.