# Work

Provider API v0.6.3 · 2 operations
Source: https://plasapi.com/provider/v0.6.3/work/

No description in the specification.

## Get Works

`GET` `/work` · `GetWorks`

### Example request

**cURL**

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

**JavaScript**

```javascript
const response = await fetch(`${process.env.PLAS_BASE_URL}/work?work_ids=882107&version=0.6.3`, {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    f"{os.environ['PLAS_BASE_URL']}/work",
    params={
        "work_ids": "882107",
        "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

- `work_ids` (In `query`, `array of string`, required) — 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".


Shared across operations: `ui_language`, `version`. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

### Responses

#### `200` Success

`GetWorksResponseBody`

Example (Generated from the schema):

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

#### `400` The list of errors.

`Errors`

Shared response, defined once for the whole API. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

Example (Generated from the schema):

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

#### `401` Bearer token invalid, missing, or expired.

No response body.

Shared response, defined once for the whole API. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

#### `404` Resource not found.

No response body.

Shared response, defined once for the whole API. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

## Search Works

`GET` `/work/search` · `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**

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

**JavaScript**

```javascript
const response = await fetch(`${process.env.PLAS_BASE_URL}/work/search?version=0.6.3`, {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    f"{os.environ['PLAS_BASE_URL']}/work/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

- `query` (In `query`, `string`, optional) — The search query.
- `page` (In `query`, `integer`, optional) — Page number (default 1).
- `size` (In `query`, `integer`, optional) — 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.

- `facet` (In `query`, [`array of SearchFacetType`](https://plasapi.com/provider/v0.6.3/schemas/#SearchFacetType), optional) — Return these facets.
- `facet_terms_size` (In `query`, `integer`, optional) — Return this number of facet terms for each requested facet (default 10).
- `sort` (In `query`, [`SearchSortingType`](https://plasapi.com/provider/v0.6.3/schemas/#SearchSortingType), optional) — Sorting
- `filter` (In `query`, `object`, optional) — 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.


Shared across operations: `ui_language`, `version`. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

### Responses

#### `200` Success

`SearchWorksResponseBody`

Example (Generated from the schema):

```json
{
  "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
}
```

#### `400` The list of errors.

`Errors`

Shared response, defined once for the whole API. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

Example (Generated from the schema):

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

#### `401` Bearer token invalid, missing, or expired.

No response body.

Shared response, defined once for the whole API. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)

#### `404` Resource not found.

No response body.

Shared response, defined once for the whole API. [See the shared contract on the version page.](https://plasapi.com/provider/v0.6.3/)