Inventory API (v8.3)

http://localhost

Table of contents

Inventory API

API for interacting with an inventory of physical resources

/inventory

GET /inventory/items

Retrieve a list of item items.

GET /inventory/items
Query Parameters
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    using CQL (indexes for item and material type)

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    barcode=="65345656554"
    
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of item items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of item records",
  "type": "object",
  "properties": {
    "items": {
      "description": "List of item records",
      "id": "items",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "item.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "items",
    "totalRecords"
  ]
}

Example:

{
  "items": [
    {
      "id": "43ec57e3-3974-4d05-a2c2-95126e087b72",
      "title": "Nod",
      "barcode": "456743454532",
      "status": {
        "name": "Available"
      },
      "materialType": {
        "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
        "name": "Book"
      },
      "permanentLocation": {
        "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
        "name": "Main Library"
      },
      "permanentLoanType": {
        "id": "11477028-d9e6-44d2-9364-5c6f51053f51",
        "name": "Reading Room"
      }
    },
    {
      "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
      "title": "Uprooted",
      "callNumber": "D11.J54 A3 2011",
      "barcode": "645398607547",
      "status": {
        "name": "Available"
      },
      "materialType": {
        "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
        "name": "Book"
      },
      "permanentLoanType": {
        "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
        "name": "Can Circulate"
      },
      "temporaryLoanType": {
        "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
        "name": "Course Reserve"
      },
      "permanentLocation": {
        "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
        "name": "Main Library"
      },
      "temporaryLocation": {
        "id": "0df935eb-f3f4-4741-9ac6-33c500174b96",
        "name": "Annex"
      }
    }
  ],
  "totalRecords": 2
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list items -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list items -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /inventory/items

Create a new item item.

POST /inventory/items
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An item record",
  "type": "object",
  "properties": {
    "id": {
      "description": "Item id",
      "type": "string"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID"
    },
    "holdingsRecordId": {
      "description": "ID of the holdings record the item is a member of",
      "type": "string"
    },
    "formerIds": {
      "type": "array",
      "description": "Previous identifiers assigned to the item",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },    
    "title": {
      "type": "string",
      "description": "Resouce title (read only, inherited from associated instance record)",
      "readonly": true
    },
    "contributorNames": {
      "description": "A list of contributor names",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The contributor name",
            "type": "string"
          }
        }
      }
    },
    "callNumber": {
      "type": "string",
      "description": "Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record)",
      "readonly": true
    },
    "barcode": {
      "description": "Text, with input likely validated by the barcode scanner",
      "type": "string"
    },
    "accessionNumber": {
      "type": "string",
      "description": "Accession number is also called inventar number. Accession number is a unique number assigned to an item in the order in which it is added to a library collection. Most libraries assign accession numbers in continous numerical sequece, but some use a code system to indicate type of material and/or year of accession in addition to order of accession"
    },

    "itemLevelCallNumber": {
      "description": "Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record). The item level call number, is the call number on item level",
      "type": "string"
    },
    "itemLevelCallNumberPrefix": {
      "description": "Prefix of the call number on the item level",
      "type": "string"
    },
    "itemLevelCallNumberSuffix": {
      "description": "Suffix of the call number on the item level",
      "type": "string"
    },
    "itemLevelCallNumberTypeId": {
      "description": "Call number type, refers to a call-number-type reference record",
      "type": "string"
    },
    "volume": {
      "description": "Volume is intended for monographs when a multipart monograph (e.g. a biography of Gerorge Bernard Shaw in three volumes)",
      "type": "string"
    },
    "enumeration": {
      "description": "Enumeration is the descriptive information for the numbering scheme of a serial, usually identified by level and a descriptive caption, e.g., level 0 = v. and level 1 = no. This means that each issue of the serial has a volume and an issue number that would appear (e.g. v.71:no.6-2)",
      "type": "string"
    },
    "chronology": {
      "description": "Chronology is the descriptive information for the dating scheme of a serial, usually identified by level, e.g., level 0 = year level 1 = month. This means that each issue of the serial has a month and a year on each issue (e.g. 1985:July-Dec.)",
      "type": "string"
    },
    "yearCaption": {
      "description": "In multipart monographs, a caption is characters used to label a level of chronology (e.g. 'year 1985')",
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "itemIdentifier": {
      "description": "Item identifier number, e.g. imported from the union catalogue (read only)",
      "type": "string"
    },
    "copyNumbers": {
      "description": "Copy number is the piece identifier. The copy number reflects if the library has one (or more) copies of a single-volume monograph; one (or more) copies of a multi-volume, (e.g. Copy 1, or C.7.)",
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "numberOfPieces": {
      "description": "Number of pieces. Used when an item is checked out or returned to verify that all parts are present (e.g. 7 CDs in a set)",
      "type": "string"
    },
    "descriptionOfPieces": {
      "description": "Text which descripe the pieces",
      "type": "string"
    },
    "numberOfMissingPieces": {
      "description": "Number of missing pieces",
      "type": "string"
    },
    "missingPieces": {
      "description": "Text which descripes the missing pieces",
      "type": "string"
    },
    "missingPiecesDate": {
      "description": "Date when the piece(s) went missing",
      "type": "string"
    },
    "itemDamagedStatusId": {
      "description": "Item Damage status Id, refers to an Item damage Status ID reference record",
      "type": "string"
    },
    "itemDamagedStatusDate": {
      "description": "Date when damage status was last changed",
      "type": "string"
    },
    "notes": {
      "description": "notes",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNoteTypeId": {
            "description": "Item note type, refers to a item-note-type reference record",
            "type": "string"
          },
          "note": {
            "description": "Text to display (e.g. action note, binding, use and reproduction)",
            "type": "string"
          },
          "staffOnly": {
            "description": "Records the fact that the record should only be displayed for staff",
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "circulationNotes": {
      "type": "array",
      "description": "Notes to be displayed in circulation processes",
      "items": {
        "type": "object",
        "properties": {
          "noteType": {
            "type": "string",
            "description": "Type of circulation process that the note applies to",
            "enum": ["Check in", "Check out"]
          },
          "note": {
            "type": "string",
            "description": "Text to display"
          },
          "staffOnly": {
            "type": "boolean",
            "description": "Records the fact that the note should only be displayed for staff",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "status": {
      "description": "The status of the item",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the item state (e.g. Available, Checked out, In transit, Awaiting pickup, On order). Default value is set to: Available",
          "type": "string"
        },
        "date": {
          "description": "Date of the current item state. E.g. date set when item state was changed by the Check out app",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "materialType": {
      "description": "Material type define what type of thing the item is",
      "type": "object",
      "properties": {
        "id": {
          "description": "Material type Id, refers to a material type reference record",
          "type": "string"
        },
        "name": {
          "description": "Material type name (e.g. Audio book, Audio disc, Computer file, Pamphelet) ",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLoanType": {
      "description": "Permanent loan type, is the default loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Permanent loan type Id, refers to a loan type reference record",
          "type": "string"
        },
        "name": {
          "description": "Permanent loan type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLoanType": {
      "description": "Temporary loan type, is the temporary loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Temporary loan type Id, refers to a loan type reference record",
          "type": "string"
        },
        "name": {
          "description": "Temporary loan type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLocation": {
      "description": "Permanent item location is the default location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed",
      "type": "object",
      "properties": {
        "id": {
          "description": "Permanent location Id, refers to a location type reference record",
          "type": "string"
        },
        "name": {
          "description": "Permanent location type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLocation": {
      "description": "Temporary item location is the temporarily location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed",
      "type": "object",
      "properties": {
        "id": {
          "description": "Temporary location Id, refers to a location type reference record",
          "type": "string"
        },
        "name": {
          "description": "Temporary location name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "effectiveLocation": {
       "type": "object",
       "description": "The effective location is used by FOLIO and other integrated systems to know the current home location for the item (read only, derived from locations on HoldingsRecord and Item)",
       "readonly": true,
       "properties": {
         "id": {
           "type": "string",
           "readonly": true
         },
         "name": {
           "description": "Effective location name",
           "type": "string",
           "readonly": true
         }
       }
    },
    "electronicAccess": {
      "description": "Whether an item is available electronically",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "Link text is used for display in place of the URL"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship Id, refers to a Relationship type reference record. Relationship between the electronic resource at the location identified and the item described in the record as a whole. (E.g. values from MARC 21, tag field 856 2nd indicator, where the values are: No information provided, Resource, Version of resource, Related resource, No display constant generate"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "Statistical code Id, refers to a Statistical code reference record",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "purchaseOrderLineIdentifier": {
      "type": "string",
      "description": "ID referencing a remote purchase order object related to this item"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "materialType",
    "permanentLoanType"
  ]
}

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created item item

Body

Media type: application/json

Type: any

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add item -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create items -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

DELETE /inventory/items

DELETE /inventory/items
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

All items deleted

GET /inventory/items/{itemId}

Retrieve item item with given {itemId}

GET /inventory/items/{itemId}
URI Parameters
  • itemId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An item record",
  "type": "object",
  "properties": {
    "id": {
      "description": "Item id",
      "type": "string"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID"
    },
    "holdingsRecordId": {
      "description": "ID of the holdings record the item is a member of",
      "type": "string"
    },
    "formerIds": {
      "type": "array",
      "description": "Previous identifiers assigned to the item",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },    
    "title": {
      "type": "string",
      "description": "Resouce title (read only, inherited from associated instance record)",
      "readonly": true
    },
    "contributorNames": {
      "description": "A list of contributor names",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The contributor name",
            "type": "string"
          }
        }
      }
    },
    "callNumber": {
      "type": "string",
      "description": "Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record)",
      "readonly": true
    },
    "barcode": {
      "description": "Text, with input likely validated by the barcode scanner",
      "type": "string"
    },
    "accessionNumber": {
      "type": "string",
      "description": "Accession number is also called inventar number. Accession number is a unique number assigned to an item in the order in which it is added to a library collection. Most libraries assign accession numbers in continous numerical sequece, but some use a code system to indicate type of material and/or year of accession in addition to order of accession"
    },

    "itemLevelCallNumber": {
      "description": "Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record). The item level call number, is the call number on item level",
      "type": "string"
    },
    "itemLevelCallNumberPrefix": {
      "description": "Prefix of the call number on the item level",
      "type": "string"
    },
    "itemLevelCallNumberSuffix": {
      "description": "Suffix of the call number on the item level",
      "type": "string"
    },
    "itemLevelCallNumberTypeId": {
      "description": "Call number type, refers to a call-number-type reference record",
      "type": "string"
    },
    "volume": {
      "description": "Volume is intended for monographs when a multipart monograph (e.g. a biography of Gerorge Bernard Shaw in three volumes)",
      "type": "string"
    },
    "enumeration": {
      "description": "Enumeration is the descriptive information for the numbering scheme of a serial, usually identified by level and a descriptive caption, e.g., level 0 = v. and level 1 = no. This means that each issue of the serial has a volume and an issue number that would appear (e.g. v.71:no.6-2)",
      "type": "string"
    },
    "chronology": {
      "description": "Chronology is the descriptive information for the dating scheme of a serial, usually identified by level, e.g., level 0 = year level 1 = month. This means that each issue of the serial has a month and a year on each issue (e.g. 1985:July-Dec.)",
      "type": "string"
    },
    "yearCaption": {
      "description": "In multipart monographs, a caption is characters used to label a level of chronology (e.g. 'year 1985')",
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "itemIdentifier": {
      "description": "Item identifier number, e.g. imported from the union catalogue (read only)",
      "type": "string"
    },
    "copyNumbers": {
      "description": "Copy number is the piece identifier. The copy number reflects if the library has one (or more) copies of a single-volume monograph; one (or more) copies of a multi-volume, (e.g. Copy 1, or C.7.)",
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "numberOfPieces": {
      "description": "Number of pieces. Used when an item is checked out or returned to verify that all parts are present (e.g. 7 CDs in a set)",
      "type": "string"
    },
    "descriptionOfPieces": {
      "description": "Text which descripe the pieces",
      "type": "string"
    },
    "numberOfMissingPieces": {
      "description": "Number of missing pieces",
      "type": "string"
    },
    "missingPieces": {
      "description": "Text which descripes the missing pieces",
      "type": "string"
    },
    "missingPiecesDate": {
      "description": "Date when the piece(s) went missing",
      "type": "string"
    },
    "itemDamagedStatusId": {
      "description": "Item Damage status Id, refers to an Item damage Status ID reference record",
      "type": "string"
    },
    "itemDamagedStatusDate": {
      "description": "Date when damage status was last changed",
      "type": "string"
    },
    "notes": {
      "description": "notes",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNoteTypeId": {
            "description": "Item note type, refers to a item-note-type reference record",
            "type": "string"
          },
          "note": {
            "description": "Text to display (e.g. action note, binding, use and reproduction)",
            "type": "string"
          },
          "staffOnly": {
            "description": "Records the fact that the record should only be displayed for staff",
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "circulationNotes": {
      "type": "array",
      "description": "Notes to be displayed in circulation processes",
      "items": {
        "type": "object",
        "properties": {
          "noteType": {
            "type": "string",
            "description": "Type of circulation process that the note applies to",
            "enum": ["Check in", "Check out"]
          },
          "note": {
            "type": "string",
            "description": "Text to display"
          },
          "staffOnly": {
            "type": "boolean",
            "description": "Records the fact that the note should only be displayed for staff",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "status": {
      "description": "The status of the item",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the item state (e.g. Available, Checked out, In transit, Awaiting pickup, On order). Default value is set to: Available",
          "type": "string"
        },
        "date": {
          "description": "Date of the current item state. E.g. date set when item state was changed by the Check out app",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "materialType": {
      "description": "Material type define what type of thing the item is",
      "type": "object",
      "properties": {
        "id": {
          "description": "Material type Id, refers to a material type reference record",
          "type": "string"
        },
        "name": {
          "description": "Material type name (e.g. Audio book, Audio disc, Computer file, Pamphelet) ",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLoanType": {
      "description": "Permanent loan type, is the default loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Permanent loan type Id, refers to a loan type reference record",
          "type": "string"
        },
        "name": {
          "description": "Permanent loan type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLoanType": {
      "description": "Temporary loan type, is the temporary loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Temporary loan type Id, refers to a loan type reference record",
          "type": "string"
        },
        "name": {
          "description": "Temporary loan type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLocation": {
      "description": "Permanent item location is the default location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed",
      "type": "object",
      "properties": {
        "id": {
          "description": "Permanent location Id, refers to a location type reference record",
          "type": "string"
        },
        "name": {
          "description": "Permanent location type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLocation": {
      "description": "Temporary item location is the temporarily location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed",
      "type": "object",
      "properties": {
        "id": {
          "description": "Temporary location Id, refers to a location type reference record",
          "type": "string"
        },
        "name": {
          "description": "Temporary location name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "effectiveLocation": {
       "type": "object",
       "description": "The effective location is used by FOLIO and other integrated systems to know the current home location for the item (read only, derived from locations on HoldingsRecord and Item)",
       "readonly": true,
       "properties": {
         "id": {
           "type": "string",
           "readonly": true
         },
         "name": {
           "description": "Effective location name",
           "type": "string",
           "readonly": true
         }
       }
    },
    "electronicAccess": {
      "description": "Whether an item is available electronically",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "Link text is used for display in place of the URL"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship Id, refers to a Relationship type reference record. Relationship between the electronic resource at the location identified and the item described in the record as a whole. (E.g. values from MARC 21, tag field 856 2nd indicator, where the values are: No information provided, Resource, Version of resource, Related resource, No display constant generate"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "Statistical code Id, refers to a Statistical code reference record",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "purchaseOrderLineIdentifier": {
      "type": "string",
      "description": "ID referencing a remote purchase order object related to this item"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "materialType",
    "permanentLoanType"
  ]
}

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"item not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /inventory/items/{itemId}

Delete item item with given {itemId}

DELETE /inventory/items/{itemId}
URI Parameters
  • itemId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete item -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"item not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /inventory/items/{itemId}

Update item item with given {itemId}

PUT /inventory/items/{itemId}
URI Parameters
  • itemId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An item record",
  "type": "object",
  "properties": {
    "id": {
      "description": "Item id",
      "type": "string"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID"
    },
    "holdingsRecordId": {
      "description": "ID of the holdings record the item is a member of",
      "type": "string"
    },
    "formerIds": {
      "type": "array",
      "description": "Previous identifiers assigned to the item",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },    
    "title": {
      "type": "string",
      "description": "Resouce title (read only, inherited from associated instance record)",
      "readonly": true
    },
    "contributorNames": {
      "description": "A list of contributor names",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The contributor name",
            "type": "string"
          }
        }
      }
    },
    "callNumber": {
      "type": "string",
      "description": "Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record)",
      "readonly": true
    },
    "barcode": {
      "description": "Text, with input likely validated by the barcode scanner",
      "type": "string"
    },
    "accessionNumber": {
      "type": "string",
      "description": "Accession number is also called inventar number. Accession number is a unique number assigned to an item in the order in which it is added to a library collection. Most libraries assign accession numbers in continous numerical sequece, but some use a code system to indicate type of material and/or year of accession in addition to order of accession"
    },

    "itemLevelCallNumber": {
      "description": "Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record). The item level call number, is the call number on item level",
      "type": "string"
    },
    "itemLevelCallNumberPrefix": {
      "description": "Prefix of the call number on the item level",
      "type": "string"
    },
    "itemLevelCallNumberSuffix": {
      "description": "Suffix of the call number on the item level",
      "type": "string"
    },
    "itemLevelCallNumberTypeId": {
      "description": "Call number type, refers to a call-number-type reference record",
      "type": "string"
    },
    "volume": {
      "description": "Volume is intended for monographs when a multipart monograph (e.g. a biography of Gerorge Bernard Shaw in three volumes)",
      "type": "string"
    },
    "enumeration": {
      "description": "Enumeration is the descriptive information for the numbering scheme of a serial, usually identified by level and a descriptive caption, e.g., level 0 = v. and level 1 = no. This means that each issue of the serial has a volume and an issue number that would appear (e.g. v.71:no.6-2)",
      "type": "string"
    },
    "chronology": {
      "description": "Chronology is the descriptive information for the dating scheme of a serial, usually identified by level, e.g., level 0 = year level 1 = month. This means that each issue of the serial has a month and a year on each issue (e.g. 1985:July-Dec.)",
      "type": "string"
    },
    "yearCaption": {
      "description": "In multipart monographs, a caption is characters used to label a level of chronology (e.g. 'year 1985')",
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "itemIdentifier": {
      "description": "Item identifier number, e.g. imported from the union catalogue (read only)",
      "type": "string"
    },
    "copyNumbers": {
      "description": "Copy number is the piece identifier. The copy number reflects if the library has one (or more) copies of a single-volume monograph; one (or more) copies of a multi-volume, (e.g. Copy 1, or C.7.)",
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "numberOfPieces": {
      "description": "Number of pieces. Used when an item is checked out or returned to verify that all parts are present (e.g. 7 CDs in a set)",
      "type": "string"
    },
    "descriptionOfPieces": {
      "description": "Text which descripe the pieces",
      "type": "string"
    },
    "numberOfMissingPieces": {
      "description": "Number of missing pieces",
      "type": "string"
    },
    "missingPieces": {
      "description": "Text which descripes the missing pieces",
      "type": "string"
    },
    "missingPiecesDate": {
      "description": "Date when the piece(s) went missing",
      "type": "string"
    },
    "itemDamagedStatusId": {
      "description": "Item Damage status Id, refers to an Item damage Status ID reference record",
      "type": "string"
    },
    "itemDamagedStatusDate": {
      "description": "Date when damage status was last changed",
      "type": "string"
    },
    "notes": {
      "description": "notes",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNoteTypeId": {
            "description": "Item note type, refers to a item-note-type reference record",
            "type": "string"
          },
          "note": {
            "description": "Text to display (e.g. action note, binding, use and reproduction)",
            "type": "string"
          },
          "staffOnly": {
            "description": "Records the fact that the record should only be displayed for staff",
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "circulationNotes": {
      "type": "array",
      "description": "Notes to be displayed in circulation processes",
      "items": {
        "type": "object",
        "properties": {
          "noteType": {
            "type": "string",
            "description": "Type of circulation process that the note applies to",
            "enum": ["Check in", "Check out"]
          },
          "note": {
            "type": "string",
            "description": "Text to display"
          },
          "staffOnly": {
            "type": "boolean",
            "description": "Records the fact that the note should only be displayed for staff",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "status": {
      "description": "The status of the item",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the item state (e.g. Available, Checked out, In transit, Awaiting pickup, On order). Default value is set to: Available",
          "type": "string"
        },
        "date": {
          "description": "Date of the current item state. E.g. date set when item state was changed by the Check out app",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "materialType": {
      "description": "Material type define what type of thing the item is",
      "type": "object",
      "properties": {
        "id": {
          "description": "Material type Id, refers to a material type reference record",
          "type": "string"
        },
        "name": {
          "description": "Material type name (e.g. Audio book, Audio disc, Computer file, Pamphelet) ",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLoanType": {
      "description": "Permanent loan type, is the default loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Permanent loan type Id, refers to a loan type reference record",
          "type": "string"
        },
        "name": {
          "description": "Permanent loan type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLoanType": {
      "description": "Temporary loan type, is the temporary loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Temporary loan type Id, refers to a loan type reference record",
          "type": "string"
        },
        "name": {
          "description": "Temporary loan type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLocation": {
      "description": "Permanent item location is the default location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed",
      "type": "object",
      "properties": {
        "id": {
          "description": "Permanent location Id, refers to a location type reference record",
          "type": "string"
        },
        "name": {
          "description": "Permanent location type name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLocation": {
      "description": "Temporary item location is the temporarily location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed",
      "type": "object",
      "properties": {
        "id": {
          "description": "Temporary location Id, refers to a location type reference record",
          "type": "string"
        },
        "name": {
          "description": "Temporary location name",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "effectiveLocation": {
       "type": "object",
       "description": "The effective location is used by FOLIO and other integrated systems to know the current home location for the item (read only, derived from locations on HoldingsRecord and Item)",
       "readonly": true,
       "properties": {
         "id": {
           "type": "string",
           "readonly": true
         },
         "name": {
           "description": "Effective location name",
           "type": "string",
           "readonly": true
         }
       }
    },
    "electronicAccess": {
      "description": "Whether an item is available electronically",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "Link text is used for display in place of the URL"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship Id, refers to a Relationship type reference record. Relationship between the electronic resource at the location identified and the item described in the record as a whole. (E.g. values from MARC 21, tag field 856 2nd indicator, where the values are: No information provided, Resource, Version of resource, Related resource, No display constant generate"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "Statistical code Id, refers to a Statistical code reference record",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "purchaseOrderLineIdentifier": {
      "type": "string",
      "description": "ID referencing a remote purchase order object related to this item"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "materialType",
    "permanentLoanType"
  ]
}

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update item -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"item not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /inventory/instances

Retrieve a list of instance items.

GET /inventory/instances
Query Parameters
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    using CQL (indexes for item and material type)

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    title="uproot*"
    
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of instance items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of instance records",
  "type": "object",
  "properties": {
    "instances": {
      "description": "List of instance records",
      "id": "instances",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "instance.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "instances",
    "totalRecords"
  ]
}

Example:

{
  "instances": [
    {
      "@context": "http://localhost:9130/inventory/instance/context",
      "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
      "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
      "source": "Local",
      "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
      "links": {
        "self": "http://localhost:9130/inventory/instance/cf23adf0-61ba-4887-bf82-956c4aae2260"
      },
      "identifiers": [
        {
          "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
          "value": "9781466636897"
        }
      ],
      "contributors": [
        {
          "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
          "name": "Samuels, Simon"
        }
      ]
    },
    {
      "@context": "http://localhost:9130/inventory/instance/context",
      "id": "ab312025-0642-45a6-8545-aa02aff1ae7c",
      "title": "ADVANCING RESEARCH METHODS WITH NEW TECHNOLOGIES.",
      "source": "Local",
      "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
      "links": {
        "self": "http://localhost:9130/inventory/instance/ab312025-0642-45a6-8545-aa02aff1ae7c"
      },
      "identifiers": [
        {
          "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
          "value": "9781466639195"
        }
      ],
      "contributors": [
        {
          "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
          "name": "Jules, Julian"
        }
      ]
    }
  ],
  "totalRecords": 2
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list instances -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list instances -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /inventory/instances

Create a new instance item.

POST /inventory/instances
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "type": "object",
  "properties": {
    "@context": {
      "description": "Instance context",
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory;  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)"
    },
    "parentInstances": {
      "description": "Array of parent instances",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Id of the parent instance",
            "type": "string"
          },
          "superInstanceId": {
            "description": "Id of the super instance",
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "description": "Id of the relationship type",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "superInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "childInstances": {
      "description": "Child instances",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subInstanceId": {
            "description": "Id of sub Instance",
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "description": "Id of the relationship type",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "subInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "ID for an alternative title qualifier"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Resource identifier value"
          },
          "identifierTypeId": {
            "type": "string",
            "description": "Resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)"
          }
        },
        "additionalProperties": false,
        "required": [
          "value",
          "identifierTypeId"
        ]
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "ID for the contributor type term defined as a referencetable in settings"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "Contributor type terms defined by the MARC code list for relators"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "List of classification schemas (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "The value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "instanceTypeId": {
      "type": "string",
      "description": "The unique term for the resource type whether it's from the RDA content term list of locally defined"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "The unique term for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string"
      }
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes), and administrative notes",
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "RDA mode of issuance is a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc."
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      }
    },
    "sourceRecordFormat": {
      "description": "Format of the instance source record, if a source record exists",
      "type": "string",
      "enum": ["MARC-JSON"],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "links": {
        "description": "Links",
        "type": "object",
        "properties": {
          "self": {
            "description": "self",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "self"
        ]
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created instance item

Body

Media type: application/json

Type: any

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add instance -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create instances -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

DELETE /inventory/instances

DELETE /inventory/instances
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

All instances deleted

GET /inventory/instances/{instanceId}

Retrieve instance item with given {instanceId}

GET /inventory/instances/{instanceId}
URI Parameters
  • instanceId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "type": "object",
  "properties": {
    "@context": {
      "description": "Instance context",
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory;  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)"
    },
    "parentInstances": {
      "description": "Array of parent instances",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Id of the parent instance",
            "type": "string"
          },
          "superInstanceId": {
            "description": "Id of the super instance",
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "description": "Id of the relationship type",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "superInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "childInstances": {
      "description": "Child instances",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subInstanceId": {
            "description": "Id of sub Instance",
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "description": "Id of the relationship type",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "subInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "ID for an alternative title qualifier"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Resource identifier value"
          },
          "identifierTypeId": {
            "type": "string",
            "description": "Resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)"
          }
        },
        "additionalProperties": false,
        "required": [
          "value",
          "identifierTypeId"
        ]
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "ID for the contributor type term defined as a referencetable in settings"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "Contributor type terms defined by the MARC code list for relators"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "List of classification schemas (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "The value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "instanceTypeId": {
      "type": "string",
      "description": "The unique term for the resource type whether it's from the RDA content term list of locally defined"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "The unique term for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string"
      }
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes), and administrative notes",
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "RDA mode of issuance is a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc."
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      }
    },
    "sourceRecordFormat": {
      "description": "Format of the instance source record, if a source record exists",
      "type": "string",
      "enum": ["MARC-JSON"],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "links": {
        "description": "Links",
        "type": "object",
        "properties": {
          "self": {
            "description": "self",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "self"
        ]
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /inventory/instances/{instanceId}

Delete instance item with given {instanceId}

DELETE /inventory/instances/{instanceId}
URI Parameters
  • instanceId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete instance -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /inventory/instances/{instanceId}

Update instance item with given {instanceId}

PUT /inventory/instances/{instanceId}
URI Parameters
  • instanceId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "type": "object",
  "properties": {
    "@context": {
      "description": "Instance context",
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory;  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)"
    },
    "parentInstances": {
      "description": "Array of parent instances",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Id of the parent instance",
            "type": "string"
          },
          "superInstanceId": {
            "description": "Id of the super instance",
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "description": "Id of the relationship type",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "superInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "childInstances": {
      "description": "Child instances",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subInstanceId": {
            "description": "Id of sub Instance",
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "description": "Id of the relationship type",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "subInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "ID for an alternative title qualifier"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Resource identifier value"
          },
          "identifierTypeId": {
            "type": "string",
            "description": "Resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)"
          }
        },
        "additionalProperties": false,
        "required": [
          "value",
          "identifierTypeId"
        ]
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "ID for the contributor type term defined as a referencetable in settings"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "Contributor type terms defined by the MARC code list for relators"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "List of classification schemas (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "The value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "instanceTypeId": {
      "type": "string",
      "description": "The unique term for the resource type whether it's from the RDA content term list of locally defined"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "The unique term for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string"
      }
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes), and administrative notes",
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "RDA mode of issuance is a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc."
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      }
    },
    "sourceRecordFormat": {
      "description": "Format of the instance source record, if a source record exists",
      "type": "string",
      "enum": ["MARC-JSON"],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "links": {
        "description": "Links",
        "type": "object",
        "properties": {
          "self": {
            "description": "self",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "self"
        ]
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update instance -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /inventory/instances/context

Provides Dublin Core context for instances

GET /inventory/instances/context

Response 200

Dublin Core context for instances

Body

Media type: application/json

Example:

{
  "@context": {
    "dcterms": "http://purl.org/dc/terms/",
    "title": "dcterms:title"
  }
}

POST /inventory/ingest/mods

POST /inventory/ingest/mods
Body

Media type: multipart/form-data

Properties:

  • file: required (file)

    MODS file containing items to ingest

Response 202

Headers
  • location: required (string)

    URI pointing to the location of ingest status

Response 400

Body

Media type: text/plain

Type: any

Example:

Cannot parse multiple files in a single request

Response 500

Body

Media type: text/plain

Type: any

GET /inventory/ingest/mods/status/{id}

Status of a MODS ingest

GET /inventory/ingest/mods/status/{id}
URI Parameters
  • id: required (string)

Response 200

Body

Media type: application/json

Example:

{
  "status": "Completed"
}

Response 500

Body

Media type: text/plain

Type: any