bblrm-specification.yaml

openapi: 3.0.0
info:
  title: Bokbasen LRM API
  description: Bokbasen LRM API
  version: 0.1.0

paths:
  /lrm/{urn}:
    get:
      description: Resolve URN representing a Resource returning its location in a Location header
      parameters:
        - in: path
          name: urn
          schema:
            type: string
          required: true
          description: The resource to retrieve by URN
          examples:
            work:
              value: bb:work:62E1FNKMKX7CF8W5WKHD19QAD8
            agent:
              value: bb:agent:02Q94MAYSX53N7PJ1HC8EEW5WW
            collection:
              value: bb:collection:E7QPNR9CWS1JZ9028Q1A2S6D7R
            subject:
              value: bb:subject:919X53SMQN2K7AEM36Y58P2YS8
      responses:
        '303':
          description: See Other
          headers:
            Location:
              example: "work/62E1FNKMKX7CF8W5WKHD19QAD8"
              schema:
                type: string
        '400':
          description: Bad request. Resource URN must be valid.

        '404':
          description: Not Found. A resource with the specified URN was not found.

        '5XX':
          description: Unexpected error.

  /lrm/work/{id}:
    description: Work by id
    get:
      description: Get Work by id
      tags:
        - work
      operationId: getWork
      parameters:
        - in: path
          description: The work to retrieve by id
          name: id
          schema:
            type: string
          required: true
          example: "89QPPRK1EDJPW835E8G64SBKEG"

        - in: header
          description: Etag, the revision of the resource in the client cache
          name: If-None-Match
          schema:
            type: integer
          example: 3

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Work'

        '304':
          description: Not Modified
        '400':
          description: Bad request. Resource ID must be valid.

        '404':
          description: Not Found. A resource with the specified ID was not found.

        '5XX':
          description: Unexpected error.

  /lrm/agent/{id}:

    get:
      description: Get Work by id
      operationId: getAgent
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          example: "02Q94MAYSX53N7PJ1HC8EEW5WW"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'

  /lrm/collection/{id}:
    get:
      description: Get Collection by id
      operationId: getCollection
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          example: "E7QPNR9CWS1JZ9028Q1A2S6D7R"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'

  /lrm/audience/{id}:
    get:
      description: Get Audience by id
      operationId: getAudience
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          example: "QBCA7FECYD5ZKDKE4HHS6B3PJ0"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Audience'

  /lrm/subject/{id}:
    get:
      description: Get Subject by id
      operationId: getSubject
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          example: "919X53SMQN2K7AEM36Y58P2YS8"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subject'

components:
  schemas:

    Work:
      type: object
      properties:
        type:
          type: string
          enum:
            - work
        id:
          type: string

        languages:
          description: The language(s) of this work ISO 639-2/B
          example: ["nob", "nno"]
          type: array
          items:
            type: string

        title:
          $ref: '#/components/schemas/WorkTitle'

        thema:
          description: Thema codes based on Editeur https://www.editeur.org/151/Thema/
          example: ["YBCS", "YXHB"]
          type: array
          items:
            type: string

        genres:
          description: Genres based on https://id.nb.no/vocabulary/ntsf/
          type: array
          items:
            type: string

        subjects:
          description: Subjects
          type: array
          items:
            $ref: "#/components/schemas/SubjectReference"

        audiences:
          description: The intended audience(s) of this work
          type: array
          items:
            $ref: "#/components/schemas/AudienceReference"

        contributors:
          type: array
          items:
            $ref: "#/components/schemas/ContributorReference"

        series:
          type: array
          items:
            $ref: "#/components/schemas/CollectionReference"


    Agent:
      type: object
      properties:
        type:
          type: string
          enum:
            - agent
        id:
          type: string
        name:
          type: string
        isni:
          type: string
        bare:
          type: string


    WorkTitle:
      type: object
      properties:
        main:
          type: string
        part:
          type: string
        number:
          type: string
        variants:
          type: array
          items:
            type: string


    ContributorReference:
      type: object
      properties:
        id:
          type: string
        role:
          type: string # Roles based on Onix List 17: Contributor role code (subset)
          enum:
            - A01
            - A08
            - A12
            - B01

    CollectionReference:
      type: object
      properties:
        id:
          type: string
        number:
          type: string

    Collection:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

    AudienceReference:
      type: object
      properties:
        id:
          type: string

    Audience:
      type: object
      properties:
        id:
          type: string
        description:
          type: string

    SubjectReference:
      type: object
      properties:
        id:
          type: string

    Subject:
      type: object
      properties:
        id:
          type: string
        label:
          type: string