Dokumentation REST API V1.7.2
Stand: November 2024
Allgemeines
Diese Anleitung beschreibt die von OPEN zur Verfügung gestellte REST API.
Zielgruppe sind Entwickler, welche die in OPEN enthaltene Funktionalität wie Recherche im Katalog, Detailanzeige von Medien, Anzeige / Ändern der Kontodaten eines Bibliotheksnutzers sowie der Services Durchführen einer Zahlung, Passwort ändern eines Bibliotheksnutzers, Ausweisverlängerung, Ausleihe, Verlängerung und Vorbestellung von Medien/Exemplaren in andere Anwendungen integrieren möchten.
Die REST API basiert auf offenen Standards, nutzt JSON als Kommunikationsformat sowie die http(s) Methoden GET, PUT, POST und DELETE.
Im Folgenden sind die jeweiligen Ressourcen sowie die jeweils möglichen Operationen im Detail beschrieben.
API-Key
Der Zugriff auf den Service ist über ein API-Key Verfahren abgesichert. Bitte beantragen Sie einen entsprechenden Schlüssel bei den zuständigen Ansprechpartnern der jeweiligen Bibliothek.
Sämtliche Anfragen an die REST-Schnittstelle müssen den persönlichen API-Key über den folgenden Parameter übertragen:
?APIKEY={APIKEY}
Anfragen ohne gültigen API-Key werden über den HTTP Statuscode 403 quittiert.
SSL
Der Zugriff auf sämtliche Ressourcen des Services ist ausschließlich über SSL möglich.
Authentifizierung
Sowohl der Zugriff auf personenbezogene Daten und Funktionen eines Lesers als auch die Nutzung von bestimmten systembezogenen Funktionen sind authentifizierungspflichtig.
Authentifizierungspflichtige Abfragen unter Leserkontext sind:
-
Get (a single) Patron
-
Get Patron Loans
-
Get Patron Reservations
-
Delete Reservation
-
Delete Patron Reservation
-
Get Patron Fees
-
Put / Post Loan Reemspquests
-
Get / Put / Post Renewal Requests
-
Get / Put / Post Reservation Requests
Post Patron Change Requests
Authentifizierungspflichtige Abfragen unter Systemkontext sind:
-
Post New Registration Requests
-
Post Password Reset Requests
-
Post Payments
-
Post Patron Card Change Requests
-
Post Patron Search Requests
-
Get Patrons (Duplicate Check)
-
Get Fees/Unpaid
Für den Zugriff auf die authentifizierungspflichtigen Ressourcen ist die Authentifizierung des besitzenden Nutzers erforderlich. Dies ist je nach Ressource entweder der betroffene Nutzer/Leser, oder der für die API eingerichtete Systembenutzer.
Der Zugriff wird ermöglicht durch die Übertragung der notwendigen Credentials im Authorization HTTP-Header. Dies sind entweder die vollständigen Base64 enkodierten Zugangsdaten des Nutzers (Basic) oder alternativ (ab v1.4) ein Zugriffstoken (Bearer).
|
HTTP-Header |
Wert |
|---|---|
|
Authorization |
Basic Base64(Nutzername:Passwort) |
|
Authorization |
Bearer AccessToken |
Anfragen ohne gültige Benutzerdaten werden über den HTTP Statuscode 403 quittiert.
Das Anfordern von Zugriffstoken wird im entsprechenden Kapitel zur Ressource Auth beschrieben.
Beispiel für die Generierung des Basic Authorization Headers
Ausweisnummer: 0000001
Passwort: secret
Authorization-Header: Basic MDAwMDAwMTpzZWNyZXQ=
Systembenutzer: OPENAPI
Passwort: secret
Authorization-Header: Basic T1BFTkFQSTpzZWNyZXQ=
Ressourcen
Die REST-API von OPEN stellt die folgenden Ressourcen bereit.
-
Auth
Die Ressource Auth dient der Abfrage von Zugriffstoken.
-
Catalogues
Die Ressource Catalogues dient der Abfrage von Mediendaten aus OPEN.
Anhand der übergebenen Medien-Id werden die Katalogdaten des Mediums ermittelt und an den REST-Client verschickt.
-
CatalogueCopies
Die Ressource CatalogueCopies dient der Abfrage von Exemplardaten aus BIBLIOTHECA.
Anhand der übergebenen Medien-Id wird eine Liste der mit dem Medium verknüpften Exemplare ermittelt und an den REST-Client verschickt. Es ist möglich über einen Parameter der Anfrage zu definieren, ob die Liste lediglich die verfügbaren Exemplare oder sämtliche Exemplare enthalten soll.
-
Zoeken
Die Ressource Search dient der Suche nach Medien im OPEN-Katalog.
Anhand des an diese Ressource im Parameter query übergebenen Suchbegriffs wird eine Suche durchgeführt und die ermittelten Treffer werden an den REST-Client verschickt.
-
Patrons
Die Ressource Patrons dient dem Auslesen von Benutzer-Daten.
Anhand der mit den Request-Properties übergebenen Zugangsdaten werden die Leserdaten ermittelt und an den REST-Client verschickt.
-
Patrons/ Loans
Die Ressource Loans dient der Abfrage der einzelnen Ausleih-Posten des Leserkontos.
Anhand der mit den Request-Properties übergebenen Zugangsdaten werden die Posten eines Leserkontos ermittelt und an den REST-Client verschickt.
-
Patrons/Reservations
Die Ressource Reservations dient der Abfrage der Vormerkungen des gerade angemeldeten Bibliotheksnutzers.
Anhand der mit den Request-Properties übergebenen Zugangsdaten werden die Vormerkungen eines Leserkontos ermittelt und an den REST-Client verschickt.
-
Patrons/ Fees
Die Ressource Fees dient der Abfrage des Gebührenkontos des gerade angemeldeten Bibliotheksnutzers.
Anhand der mit den Request-Properties übergebenen Zugangsdaten werden die offenen Gebühren eines Leserkontos ermittelt und an den REST-Client verschickt.
-
Patrons/Payments
Die Ressource Payments dient der Durchführung einer Zahlung.
-
Loan Request s
Die Ressource LoanRequests dient der Durchführung von Ausleihanfragen auf Exemplare. Anhand einer in einem POST-Request als Parameter übergebenen Exemplar-Id kann eine Ausleihe für dieses Exemplar angefordert werden. Diese kann dann über einen PUT-Request durchgeführt werden. -
Renewal Requests
Die Ressource RenewalRequests dient der Durchführung und Abfrage von Verlängerungsanfragen auf Exemplare. Anhand einer in einem POST-Request als Parameter übergebenen Exemplar-Id kann eine Verlängerung für dieses Exemplar angefordert werden. Diese kann dann über einen PUT -Request durchgeführt werden. Angeforderte Verlängerungen können über GET aus dieser Ressource angefordert werden.
-
Reservation Requests
Die Ressource ReservationRequests dient der Durchführung und Abfrage von Vormerkungen auf Exemplare oder Medien. Anhand einer in einem POST-Request als Parameter übergebenen Medien- oder Exemplar-Id kann eine Vormerkung für dieses Katalog-Item angefordert werden. Diese kann dann über einen PUT-Request festgeschrieben werden. Angeforderte Vormerkungen können über GET aus dieser Ressource geholt werden. -
Registration Requests
Die Ressource RegistrationRequests dient der Erstellung neuer Leser.
-
Patron Password Reset Requests
Die Ressource PatronPasswordResetRequests dient dem Zurücksetzen eines Leser-Passworts. -
Patron Account Renewal Requests
Die Ressource PatronAccountRenewalRequests dient der Durchführung einer Ausweisverlängerung. -
Patron Card Change Requests
Die Ressource PatronCardChangeRequests dient dem Setzen einer Gültigkeit des Leserausweis (Gültig bis). -
Patron Change Requests
Die Ressource PatronChangeRequests dient dem Ändern von Benutzerdaten. -
Pickup Branches
Die Ressource PickupBranches dient der Abfrage von Zweigstelleninformationen.
Mit Hilfe eines GET-Requests können entweder Daten zu allen in der Bibliothek vorhandenen Zweigstellen oder, bei zusätzlicher Angabe einer Ausweisnummer, Daten zu der/den Abholzweigstelle(n) eines konkreten Lesers aus der Ressource geholt werden.
-
Fees/Unpaid
Die Ressource Fees/Unpaid dient der Abfrage offener Gebühren aller Leser.
-
Branches
Die Ressource Branches dient der Abfrage von Zweigstelleninformationen.
-
CopyStatuses
Die Ressource CopyStatuses dient der Abfrage von Exemplarstatusinformationen.
-
MediaGroups
Die Ressource MediaGroups dient der Abfrage von Mediengruppeninformationen.
-
UserGroups
Die Ressource UserGroups dient der Abfrage von Benutzergruppeninformationen.
Auth
Über die Auth-Ressource können Zugriffstoken angefordert werden, welche für die Anfrage authentifizierungspflichtiger Ressourcen herangezogen werden können.
Die Lieferung von Refresh-Token ist optional und muss über die entsprechenden Angaben im AuthRequest angefordert werden. Default (leerer AuthRequest) führt dazu, dass kein Refresh-Token generiert wird.
Bei Anforderung von RefreshTokens müssen immer beide Parameter angegeben werden.
Data Types
Request
|
AuthRequest |
|||
|---|---|---|---|
|
Name |
Type |
Länge |
Description |
|
ClientUsername(*) |
String |
20 |
Systembenutzer, mit dem das RefreshToken verknüpft wird. Muss zusammen mit TimeToLive angegeben werden. |
|
TimeToLive(*) |
Int |
Gültigkeitsdauer des RefreshTokens in Minuten. |
|
(*) Optional
Response
TokenResponse
|
Name |
Type |
Description |
|---|---|---|
|
AccessToken |
String |
AccessToken für die Authentifizierung |
|
AccessTokenExpires |
DateTime |
Zeitpunkt bis zu dem das Token gültig ist. Format: 2020-08-25T08:37:26+02:00 |
|
RefreshToken |
String |
RefreshToken, um neue AccessTokens zu generieren Ist einmalig gültig. Beim Anfordern von AccessTokens über die Ressource Auth/Refresh wird ein neues RefreshToken übermittelt. |
|
RefreshTokenExpires |
DateTime |
Zeitpunkt bis zu dem das Token gültig ist. Format: 2020-08-25T08:37:26+02:00 |
|
PasswordChangeRequired |
bool |
Wert des Flags in der Datenbank, welches bestimmt ob ein Leser sein Passwort bei der nächsten Anmeldung in OPEN ändern muss. |
Functions
Get an Authorization Token
Erstellt Zugriffstoken für die Authentifizierung über Tokens.
Die Autorisierung erfolgt über den Benutzer im Authorization-Header (Format Basic).
Enkodierung des Bodys ist UTF-8.
Result
TokenResponse
POST /auth
Parameters
None
Body
AuthRequest
Examples
Anforderung mit RefreshToken:
POST /auth?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
Content-Type: application/json
{
"ClientUsername":"OPENAPI",
"TimeToLive": 20160
}
Anforderung ohne RefreshToken:
POST /auth?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
Content-Type: application/json
{
}
Refresh
Refresh an Authorization Token
Erneuert Zugriffstoken für die Authentifizierung über Tokens.
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header. (Format Basic)
Enkodierung des Bodys ist UTF-8.
Data Types
Request
AuthRefreshRequest
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
AccountNumber |
String |
15 |
Ausweisnummer |
|
RefreshToken |
String |
RefreshToken aus dem AuthRequest bzw. dem AuthRefreshRequest |
Functions
Get a new Authorization Token (Refresh)
Fordert ein neues Zugriffstoken unter Verwendung eines gültigen Refresh Tokens an.
Result
TokenResponse (siehe Ressource Auth)
POST /auth/refresh
Parameters
None
Body
AuthRefreshRequest
Example
POST /auth/refresh?APIKey=[***] HTTP/1.1
Authorization: Basic T1BFTkFQSTpzZWNyZXQ=
Content-Type: application/json
{
"AccountNumber":"0000001",
" RefreshToken ":"aaaAAAaaaaAAAAaaAA"
}
Catalogues
Abfrage von Mediendaten
Details zu Medien können über die Id abgefragt werden.
Data Types
Catalogue
|
Name |
Type |
Description |
|---|---|---|
|
IsComprehensiveItem |
Bool |
True, wenn es sich um ein Gesamtwerk handelt. False, wenn es sich um ein Medium oder ein unselbstständiges Werk handelt (siehe MediaType). |
|
IsEMedium |
Bool |
True, wenn es sich um ein e-Medium handelt. False, wenn es sich um ein physisches Medium handelt. |
|
Id |
String |
BIBLIOTHECA Medien-Nummer |
|
Title |
String |
Hauptsachtitel |
|
SubTitle |
String |
Untertitel |
|
MediaGroup |
MediaGroupInformation |
Mediengruppe des Mediums (Kürzel und Beschreibung) |
|
MediaType |
String |
Medientyp (Kürzel) |
|
Authors |
List<String> |
Verfasser |
|
RecordIdentifier |
String |
Medienkennzeichen |
|
ProductionYear |
String |
Erscheinungsjahr |
|
Publisher |
String |
Verlag und Verlagsort (Verlag, Verlagsort) |
|
Parent |
String |
Mediennr. des übergeordneten Werks |
|
ParentTitle |
String |
Titel des übergeordneten Werks |
|
Children |
List<String> |
Die untergeordneten Werke (Mediennummern) |
|
AgeRating |
String |
Altersfreigabe |
|
AttachedItems |
List<String> |
Beifügungen |
|
VolumeNumberInfo |
String |
Bandangaben |
|
EMedium |
String |
Link zum e-Medium |
|
Links |
List<String> |
Links |
|
Systematics |
List<String> |
Systematik |
|
SubjectTypes |
List<String> |
Interessenkreise |
|
Isbn |
String |
ISBN |
|
Isbn2 |
String |
2. ISBN |
|
Issn |
String |
ISSN/ |
|
Ean |
String |
EAN |
|
CoverUrl |
String |
URL zu dem Cover |
|
SeriesTitle |
String |
Reihentitel |
|
KeyWords |
String |
Schlagwörter |
|
PersonsInvolved |
List<String> |
Beteiligte Personen |
|
Languages |
List<String> |
Sprachen |
|
OriginalTitle |
String |
Originaltitel |
|
Footnote |
String |
Fußnote |
|
Annotation |
String |
Annotation |
|
Availability |
Int |
Verfügbarkeit |
|
MediaGroupInformation |
||
|---|---|---|
|
Name |
Type |
Description |
|
Id |
String |
ID der Mediengruppe |
|
Description |
String |
Name der Mediengruppe |
Werte von MediaType:
M (Medium), U (Unselbstständiges Werk)
Functions
GET a single Catalogue
Liefert die Details zu einem Medium.
Result
Catalogue
GET /catalogues/{id}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
BIBLIOTHECA Medien-Nummer |
Example
GET https://localhost /OPEN/RESTv1/Catalogues/0143236?APIKey=[***] HTTP/1.1
CatalogueCopies
Über die Sub-Ressource CatalogueCopies können die Exemplardaten des Mediums abgefragt werden.
Data Types
CatalogueCopy
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
BIBLIOTHECA Exemplar-Nummer |
|
Branch |
LocationInformation |
Zweigstelle |
|
RecordIdentifier |
String |
Medienkennzeichen des Exemplars |
|
SignatureColor |
String |
Signaturfarbe (RGB) |
|
Bin |
String |
Bin |
|
CopyStatus |
CopyStatusInformation |
Status |
|
ReservationsCount |
Int |
Anzahl Vorbestellungen |
|
IsAvailable |
Bool |
Verfügbarkeit (ja/nein) |
|
DueDate |
String |
Frist |
|
Comments |
String |
Ausleihhinweise |
|
LoanLocation |
LocationInformation |
Die aktuelle Ausleihstelle |
|
Barcode |
String |
Barcode |
|
MediaGroup |
MediaGroupInformation |
Mediengruppe (Kürzel und Beschreibung) |
|
FirstLocation |
String |
Signatur |
|
SecondLocation |
String |
Standort 2 |
|
ThirdLocation |
String |
Standort 3 |
|
AgeRating |
String |
Altersfreigabe |
CopyStatusInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID des Status |
|
Description |
String |
Name des Status |
Werte von CopyStatusInformation (die Bibliothek kann zudem eigene Status
definieren):
E/Entliehen, P/Präsenzbestand, T/Transport, V/Verfügbar, Z/Zurückgelegt, t/Zum Transport
LocationInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID des Standortes |
|
Description |
String |
Name des Standortes |
MediaGroupInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Mediengruppe |
|
Description |
String |
Name der Mediengruppe |
Functions
GET a list of CatalogueCopies for a specific catalogue
Liefert alle Exemplare eines Mediums.
Result
Array<CatalogueCopy>
GET /catalogues/{id}/copies
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
BIBLIOTHECA Medien-Nummer |
Example
https://localhost /OPEN/RESTv1/Catalogues/0143236/Copies?APIKey=[***] HTTP/1.1
GET a list of CatalogueCopies for a specific catalogue
Liefert alle Exemplare eines Mediums mit der Möglichkeit, diese auf die verfügbaren Exemplare einzuschränken.
Result
Array<CatalogueCopy>
GET /catalogues/{id}/copies?onlyAvailable={onlyAvailable}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
BIBLIOTHECA Medien-Nummer |
|
onlyAvailable |
String |
True, wenn nur die verfügbaren Exemplare selektiert werden. |
Example
https://localhost /OPEN/RESTv1/Catalogues/0143236/Copies?onlyAvailable=true&APIKey=[***]
HTTP/1.1
Patrons
Abfrage von Kontodaten des aktuellen Benutzer s
Personenbezogene Daten des Benutzers können über die Ressource Patrons sowie deren Subressourcen Loans, Reservations und Fees abgefragt werden.
Die Id des Nutzers sämtlicher Anfragen an die Ressource sowie deren Subressourcen muss übereinstimmen mit der über den Header gesendeten Autorisierungsinformation (Username sowie passendes Password, alternativ Token).
Data Types
PatronAccount
|
Name |
Type |
Description |
|---|---|---|
|
FirstName |
String |
Vorname |
|
LastName |
String |
Nachname |
|
Address |
String |
Anschrift |
|
PostalCode |
String |
Postleitzahl |
|
City |
String |
Wohnort |
|
PhoneNumber |
String |
Festnetznummer |
|
MobileNumber |
String |
Mobilfunknummer |
|
|
String |
E-Mail-Adresse |
|
Age |
Int |
Alter (bei Institutionen null) |
|
UserGroup |
UserGroupInformation |
Benutzergruppe |
|
AccountNumber |
String |
Ausweisnummer |
|
AccountActive |
Bool |
Gültigkeit Leserkonto |
|
AccountValidTill |
String |
Gültigkeitsende der Benutzungsgebühr für den Leserausweis (Bezahlt bis) |
|
CardValidTill |
String |
Gültigkeitsende Leserausweis (Gültig Bis) |
|
AccountMessage |
String |
Leserhinweis |
|
Branch |
LocationInformation |
Heimatzweigstelle |
|
AccountId |
String |
Benutzernummer |
|
PasswordChangeRequired |
bool |
Wert des Flags in der Datenbank, welches bestimmt ob ein Leser sein Passwort bei der nächsten Anmeldung in OPEN ändern muss. |
UserGroupInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Benutzergruppe |
|
Description |
String |
Name der Benutzergruppe |
Functions
GET a single Patron
Liefert die Daten des aktuellen Benutzers.
GET /patrons/{id}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
Leserausweis-Nummer |
Example
GET https://localhost/OPEN/RESTv1/Patron...1?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
Loans
Abfrage von Ausleihdaten und Durchführen einer Ausleihe für den aktuellen Benutzer.
Data Types
Loan
|
Name |
Type |
Description |
|---|---|---|
|
CatalogueCopyId |
String |
Exemplar-Nummer |
|
CatalogueId |
String |
Medien-Nummer |
|
LoanType |
String |
Art des Ausleihe-Postens |
|
DelayFeeAmount |
Decimal |
Gebühr bei verspäteter Rückgabe |
|
DueDate |
String |
Ausleihfrist |
|
Isbn |
String |
ISBN des Ausleihe-Postens |
|
Isbn2 |
String |
2. ISBN des Ausleihe-Postens |
|
Ean |
String |
EAN des Ausleihe-Postens |
|
CoverUrl |
String |
URL zu dem Cover des Ausleihe-Postens |
|
Title |
String |
Titel |
|
PickupLocation |
LocationInformation |
Abholzweigstelle |
|
LoanLocation |
LocationInformation |
Ausleihzweigstelle |
Werte von LoanType:
|
LoanType |
Description |
|---|---|
|
Loan |
Ausleihe |
|
Extension |
Verlängerung |
|
ReadyForCollection |
Abholbereit |
|
Reminder |
Mahnung |
|
RemoteLoan |
Fernleihe |
|
RemoteReadyForCollection |
Fernleihe zum Abholen |
|
RemoteExtension |
Fernleihe-Verlängerung |
|
RemoteReminder |
Fernleihe in Mahnung |
Functions
GET Loans
Liefert alle Ausleihen des aktuellen Benutzers.
Result
Array<Loan>
GET /patrons/{id}/Loans
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
Leserausweis-Nummer |
Example
GET https://localhost /OPEN/RESTv1/Patrons/07005311/Loans?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
Reservations
Abfrage von Vormerkungen des aktuellen Benutzers
Data Types
Reservation
|
Name |
Type |
Description |
|---|---|---|
|
CatalogueId |
String |
BIBLIOTHECA Medien-Nummer |
|
DueDate |
String |
Vormerkung gültig bis |
|
Isbn |
String |
ISBN des vorgemerkten Titels |
|
Isbn2 |
String |
2. ISBN des vorgemerkten Titels |
|
Ean |
String |
EAN |
|
CoverUrl |
String |
URL zu dem Cover des vorgemerkten Titels |
|
PickupLocation |
LocationInformation |
Abholzweigstelle |
|
Title |
String |
Titel |
DeleteReservationResponse
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
Functions
GET Reservations
Liefert alle Vormerkungen des aktuellen Benutzers.
Result
Array<Reservation>
GET /patrons/{id}/Reservations
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
Leserausweis-Nummer |
Example
GET https://localhost /OPEN/RESTv1/Patrons/07005311/Reservations?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
DELETE Reservation
Löscht eine Vormerkung.
Result
Array<Reservation>
GET /patrons/{id}/Reservations/{catalogueId}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
Leserausweis-Nummer |
|
catalogueId |
String |
15 |
Medien-Nummer der Vormerkung |
Example
DELETE https://localhost /OPEN/RESTv1/Patrons/07005311/Reservations /0000123 ?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
Fees
Abfrage von offenen Gebühren des aktuellen Benutzers
Data Types
Fee
|
Name |
Type |
Description |
|---|---|---|
|
CatalogueId |
String |
BIBLIOTHECA Medien-Nummer (wenn es sich um eine medienbezogene Gebühr handelt) |
|
Amount |
Decimal |
Betrag |
|
Description |
String |
Beschreibung der Kostenart (z.B. Verlängerung, Vormerkung, Ausweisverlängerung) |
|
Isbn |
String |
ISBN (wenn es sich um eine medienbezogene Gebühr handelt) |
|
Isbn2 |
String |
2. ISBN (wenn es sich um eine medienbezogene Gebühr handelt) |
|
Ean |
String |
EAN (wenn es sich um eine medienbezogene Gebühr handelt) |
|
CoverUrl |
String |
URL zu dem Cover (wenn es sich um eine medienbezogene Gebühr handelt) |
|
Id |
Number |
Id der Gebühr |
Functions
GET Fees
Liefert alle offenen Gebühren des aktuellen Benutzers.
Result
Array<Fee>
GET /patrons/{id}/Fees
Para meters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
Leserausweis-Nummer |
Example
GET https://localhost /OPEN/RESTv1/Patrons/07005311/Fees?APIKey=[***] HTTP/1.1
Authorization: Basic MDAwMDAwMTpzZWNyZXQ=
Payments
Durchführen einer Zahlung
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header.
Enkodierung des Bodys ist UTF-8.
DataTypes
Payment
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
Description |
String |
248 |
Beschreibung der Zahlung |
|
FeeIds |
List<Int> |
Liste von Gebühren-IDs |
|
|
ExternalId(*) |
String |
100 |
Externe ID |
|
Type |
String |
Art der Zahlung |
(*) Optional
Werte von Type:
|
Type |
Description |
|---|---|
|
Cash |
Bar |
|
Epay |
Elektronische Zahlung |
Payment Response
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessage:
|
RequestMessage |
Description |
|---|---|
|
InvalidParameters |
Anfrage nicht gültig. Bsp.: Ungültige FeeIds, Ausweisnummer |
Functions
POST Payments
Erstellt eine Zahlung.
Result
PaymentResponse
POST patrons/{id}/payments
Para meters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
id |
String |
15 |
Leserausweis-Nummer |
Example
POST /patrons/{id}/payments?APIKey=[***] HTTP/1.1
{
"Description":"Zahlung über OPEN-API",
"FeeIds”:[1,2,3,4,5],
"Type":"Epay"
}
Zoeken
Durchführen einer Suche im Katalog
Suchen können durch die Übergabe einer Solr Search Query durchgeführt werden. Wird kein spezifisches Feld angegeben, wird bei einer ODER-verknüpften Suche in nachfolgenden Feldern gesucht:
-
Title, SubTitle, SeriesTitle, OriginalTitle, AuthorDescriptions, KeyWords, AttachedItems, Attachment
Für eine UND-verknüpfte Suche muss jeweils explizit das Wort ‚And‘ vorangestellt werden.
Es wird absteigend nach der Relevanz (d.h. abhängig von der Suche) sortiert.
Felder, in denen explizit gesucht werden kann (<Field name>:<value>)
|
Name |
Description |
|---|---|
|
Title |
siehe Beschreibung bei CatalogueSearchResult |
|
SubTitle |
siehe Beschreibung bei CatalogueSearchResult |
|
SeriesTitle |
siehe Beschreibung bei CatalogueSearchResult |
|
OriginalTitle |
Originaltitel |
|
AcquisitionDate |
Zugangsdatum des Exemplars |
|
ProductionYear |
siehe Beschreibung bei CatalogueSearchResult |
|
AuthorDescriptions |
Verfasser (Beschreibung) |
|
SubjectTypeDescriptions |
Interessenskreise (Beschreibung) |
|
MediaGroupDescription |
Mediengruppen (Beschreibung) |
|
ISBNAndISSN |
ISBN/ISBN2/ISSN |
|
MediumIdentifier |
Medienkennzeichen |
|
KeyWords |
Schlagwörter |
|
Branches |
Zweigstellen |
|
AvailableBranches |
Verfügbare Exemplare in diesen Zweigstellen |
|
Languages |
Sprachen |
|
AuthorFullMatch |
Vollständiger Autoren-Name (Vor- und Nachname) |
|
SystematicDescriptions |
Systematiken |
|
AttachedItems |
Beilagen |
|
Attachment |
Beifügung |
|
FirstAuthorDescription |
1. Verfasser (Beschreibung) |
Data Types
CatalogueSearchResponse
|
Name |
Type |
Description |
|---|---|---|
|
TotalCount |
Int |
Gesamt-Anzahl der Treffer |
|
Results |
List<CatalogueSearchResult> |
Treffer |
CatalogueSearchResult
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
BIBLIOTHECA Medien-Nummer |
|
IsComprehensiveItem |
Bool |
True, wenn es sich um ein Gesamtwerk handelt. False, wenn es sich um ein Medium oder ein unselbstständiges Werk handelt. |
|
Parent |
String |
Übergeordnete Mediennummer des Gesamtwerks |
|
ParentTitle |
String |
Titel des Gesamtwerks |
|
Title |
String |
Hauptsachtitel |
|
SubTitle |
String |
Untertitel |
|
SeriesTitle |
String |
Reihentitel |
|
VolumeNumberInfo |
String |
Bandangaben |
|
Authors |
List<String> |
Verfasser |
|
ProductionYear |
String |
Erscheinungsjahr |
|
Publisher |
String |
Verlag |
|
MediaGroup |
MediaGroupIn-formation |
Mediengruppe des Mediums |
|
RecordIdentifier |
String |
Medienkennzeichen des Mediums |
|
Availability |
Int |
Verfügbarkeit (Anzahl verfügbarer Exemplare) |
|
IsbnOrIssn |
List<String> |
ISBN / ISSN |
|
Ean |
String |
EAN |
|
CoverUrl |
String |
URL zu dem Cover |
MediaGr oupInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Mediengruppe |
|
Description |
String |
Name der Mediengruppe |
Functions
GET a Search Result
Führt eine Suche im Katalog durch.
Result
CatalogueSearchResponse
GET/search
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
query |
String |
Suchbegriff(e) |
|
Pageindex |
String |
Seitenindex |
|
Pagesize |
String |
Seitengröße (default: 20, max: 100) |
Examples
1. Volltextsuche nach "Duden"
GET https://localhost/OPEN/RESTv1/Search...=1&pageSize=10
2. Suche nach Titeln mit dem Begriff "it" und dem Serientitel "informatik"
GET
https://localhost/OPEN/RESTv1/Search?query= (Title:it) AND (SeriesTitle:informatik)&ApiKey=[***]&pageIndex=1&pageSize=20
3. Suche nach Titeln mit dem Begriff "it" oder dem Serientitel "informatik"
GET
https://localhost/OPEN/RESTv1/Search?query= (Title:it) OR (SeriesTitle:informatik)&ApiKey=[***]&pageIndex=1&pageSize=20
4. Suche nach Titeln mit Zugangsdatum in einem bestimmten Bereich:
01.01.2021 – 31.08.2021
GET
https://localhost/OPEN/RESTv1/Search?query= AcquisitionDate:[20210101 TO 20210831] &ApiKey=[***]&pageIndex=1&pageSize=20
LoanRequests
Durchführen von Ausleihen.
Der Ausleihprozess in OPEN erfolgt über mind. 2 Schritte.
-
Ausleihe anfragen (request)
Eine Ausleihe muss über POST angefragt werden. Über die Antwort erhält man Informationen über das Ergebnis der Anfrage. Eine Anfrage ist entweder gültig (d.h. eine Ausleihe kann durchgeführt werden) oder ungültig (d.h. eine Ausleihe kann aus bestimmten Gründen nicht durchgeführt werden).
Im Falle einer gültigen Anfrage erhält man eine eindeutige ID sowie weitere Informationen zu dem zu erwartenden Ergebnis der Ausleihe wie u.U. entstehenden Gebühren, Fristdatum etc.
Im Falle einer ungültigen Anfrage können die Gründe der Ablehnung über RequestMessages abgefragt und dem Kunden angezeigt werden.
-
Ausleihe bestätigen (commit)
Über PUT der Id einer gültigen Ausleihanfrage kann die Ausleihe endgültig (u.U. kostenpflichtig) durchgeführt werden.
Der Benutzer wird über die mit dem Header zu sendende Autorisierungsinformation (Username sowie passendes Password) ermittelt.
Data Types
LoanRequest
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Ausleihanfrage |
|
RequestState |
String |
Ergebnis der Ausleihanfrage |
|
RequestMessages |
List<String> |
Statusmeldungen zur Ausleihanfrage |
|
Fee |
Decimal |
Gebühr für die Ausleihe |
|
DueDate |
String |
Frist-Datum |
|
ItemId |
String |
Exemplar-Identifier des auszuleihenden Mediums |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Unconfirmed |
Unbestätigt |
|
ConfirmedByUser |
wird überprüft |
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessages:
|
RequestMessage |
Description |
|---|---|
|
CopyCantBeRetrievedFromBibPlus |
Exemplar kann nicht aus BIBLIOTHECA ausgelesen werden |
|
FeeLimitExceeded |
Maximale Gebührengrenze erreicht |
|
ReminderLevelExceeded |
Maximale Mahnstufe des Benutzerkontos erreicht |
|
NumberOfLoansExceeded |
Die Gesamtausleihzahl ist überschritten |
|
NumberOfLoansForMediaGroupExceeded |
Die Ausleihzahl für die Mediengruppe ist überschritten |
|
InvalidCopyStatusForLoan |
Exemplar nicht ausleihbar |
|
LoanOfReservedNotPossible |
Ausleihe eines vorbestellten Exemplars nicht möglich |
|
UserIsBlockedforMediaGroup |
Der Benutzer ist für diese Mediengruppe gesperrt |
|
AgeCheckFailedLoan |
Exemplar kann aufgrund der Altersbeschränkung nicht ausgeliehen werden |
|
NoLoanDuplicateRequestCopyLoaned |
Das Exemplar ist bereits auf den Benutzer ausgeliehen |
|
PatronAccountMustBeResubmitted |
Das Wiedervorlagedatum des Benutzerkontos liegt in der Vergangenheit |
|
AccountNotPaid |
Der Ausweis des Benutzers ist abgelaufen |
|
UserHadPreviouslyBorrowedMedium |
Der Benutzer hatte das Medium früher schon ausgeliehen |
Functions
Add a LoanRequest
Erstellt eine neue Ausleihanfrage.
Result
LoanRequest
POST /loanrequests/{itemId}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
itemId |
String |
15 |
Exemplar-Identifier des auszuleihenden Mediums |
Example
POST https://localhost /OPEN/RESTv1/ loan request s ? itemId =0005454001&APIKey=[***] HTTP/1.1
Confirm LoanRequests
Bestätigt eine Ausleihanfrage.
Result
Array<LoanRequest>
PUT /loanrequests/{id}
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
id |
String |
IDs der Ausleihanfrage |
Example
PUT https://localhost /OPEN/RESTv1/ loan request s /{id}?APIKey=[***] HTTP/1.1
RenewalRequests
D urchführen von Verlängerungen
Der Verlängerungsprozess in OPEN erfolgt über mind. 2 Schritte.
-
Verlängerung anfragen (request)
Eine Verlängerung für eine bestehende Ausleihe muss über POST angefragt werden. Über die Antwort erhält man Informationen über das Ergebnis der Anfrage. Eine Anfrage ist entweder gültig (d.h. eine Verlängerung kann durchgeführt werden) oder ungültig (d.h. eine Verlängerung kann aus bestimmten Gründen nicht durchgeführt werden).
Im Falle einer gültigen Anfrage erhält man eine eindeutige ID sowie weitere Informationen zu dem zu erwartenden Ergebnis der Verlängerung wie u.U. entstehenden Gebühren, neues Fristdatum etc.
Im Falle einer ungültigen Anfrage können die Gründe der Ablehnung über RequestMessages abgefragt und dem Kunden angezeigt werden.
-
Verlängerung bestätigen (commit)
Über PUT der Id einer gültigen Verlängerungsanfrage kann die Verlängerung endgültig (u.U. kostenpflichtig) durchgeführt werden.
Der Benutzer wird über die mit dem Header zu sendende Autorisierungsinformation (Username sowie passendes Password) ermittelt.
Data Types
LoanRenewalRequest
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Verlängerungsanfrage |
|
RequestState |
String |
Ergebnis der Verlängerungsanfrage |
|
RequestMessages |
List<String> |
Statusmeldungen zu Verlängerungsanfragen |
|
Fee |
Decimal |
Gebühr für die Verlängerung |
|
DelayFee |
Decimal |
Zusätzliche Gebühr bei verspäteter Rückgabe |
|
DueDate |
String |
Frist-Datum |
|
CurrentNumberOfRenewals |
Int |
Aktuelle Anzahl Verlängerungen |
|
NewNumberOfRenewals |
Int |
Anzahl von Verlängerungen nach der aktuellen Anfrage |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Unconfirmed |
Unbestätigt |
|
ConfirmedByUser |
wird überprüft |
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessages:
|
RequestMessage |
Description |
|---|---|
|
FeeLimitExceeded |
Maximale Gebührengrenze erreicht |
|
ReminderLevelExceeded |
Maximale Mahnstufe des Benutzerkontos erreicht |
|
ExtensionOfMissingNotPossible |
Verloren gemeldete Exemplare können nicht verlängert werden |
|
CopyInReminderState |
Exemplar bereits gemahnt |
|
ExtensionNotPossibleForMedium |
Medium von der Verlängerung ausgeschlossen |
|
MaximumExtensionLengthExceeded |
Maximale Dauer von Verlängerungen erreicht |
|
MaximumFollowUpExtensionsExceeded |
Maximale Anzahl an aufeinanderfolgenden Verlängerungen erreicht |
|
EarliestPossibleExtensionDateNotReached |
Zum jetzigen Zeitpunkt noch keine Verlängerung möglich |
|
NewDueDateCannotBeBeforeDueDate |
Neues Fristdatum darf nicht vor dem Leihfristende liegen |
|
LatestPossibleExtensionDateExceeded |
Ausleihfrist des Mediums überschritten |
|
ExtensionOfReservedNotPossible |
Verlängerung eines vorbestellten Exemplars nicht möglich |
|
InvalidExtensionLengthParameter |
(Verlängerungsintervall ist auf 0 Tage eingestellt) Bitte wenden Sie sich an die Bibliothek. |
Functions
GET a single RenewalRequest
Liefert eine offene Verlängerungsanfrage.
Result
LoanRenewalRequest
GET /renewalrequests/{id}
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
id |
String |
Id einer offenen Verlängerungsanfrage |
Example
GET https://localhost /OPEN/RESTv1/renewalrequests/id?APIKey=[***] HTTP/1.1
GET all RenewalRequests
Liefert alle offenen Verlängerungsanfragen des aktuellen Benutzers.
Result
Array<LoanRenewalRequest>
GET /renewalrequests
Example
GET https://localhost /OPEN/RESTv1/renewalrequests?APIKey=[***] HTTP/1.1
Add a RenewalRequest
Erstellt eine neue Verlängerungsanfrage.
Result
Array<LoanRenewalRequest>
POST /renewalrequests/{cataloguecopyids}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
cataloguecopyids |
String |
15 |
Liste von Exemplarnummern der zu verlängernden Medien (Komma-separiert) |
Example
POST https://localhost /OPEN/RESTv1/renewalrequests? cataloguecopyids=0005454001&APIKey=[***] HTTP/1.1
Confirm RenewalRequests
Bestätigt eine oder mehrere Verlängerungsanfragen.
Result
Array<LoanRenewalRequest>
PUT /renewalrequests/{ids}
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
ids |
String |
Liste von IDs der Verlängerungsanfragen (Komma-separiert) |
Example
PUT https://localhost /OPEN/RESTv1/renewalrequests/{ids}?APIKey=[***] HTTP/1.1
ReservationRequests
D urchführen von Vormerkungen
Der Vormerkungsprozess in OPEN erfolgt über mind. 2 Schritte.
-
Vormerkung anfragen (request)
Eine Vormerkung für Medien und/oder konkrete Exemplare muss über POST angefragt werden. Über die Antwort erhält man Informationen über das Ergebnis der Anfrage. Eine Anfrage ist entweder gültig (d.h. eine Vormerkung kann durchgeführt werden) oder ungültig (d.h. eine Vormerkung kann aus bestimmten Gründen nicht durchgeführt werden).
Im Falle einer gültigen Anfrage erhält man eine eindeutige ID sowie weitere Informationen zu dem zu erwartenden Ergebnis der Vormerkung wie u.U. entstehenden Gebühren.
Im Falle einer ungültigen Anfrage können die Gründe der Ablehnung über RequestMessages abgefragt und dem Kunden angezeigt werden.
-
Vormerkung bestätigen (commit)
Über PUT der Id einer gültigen Vormerkungsanfrage kann die Vormerkung endgültig (u.U. kostenpflichtig) durchgeführt werden.
Der Benutzer wird über die mit dem Header zu sendende Autorisierungsinformation (Username sowie passendes Password) ermittelt.
Data Types
LoanReservationRequest
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis der Vormerkungsanfrage |
|
RequestMessages |
List<String> |
Statusmeldungen zu Vormerkungsanfragen |
|
Hashcode |
String |
ID der Vormerkung |
|
PickupLocationId |
String |
ID der Abholzweigstelle |
|
Fee |
Decimal |
Gebühr für die Vormerkung |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Unconfirmed |
Unbestätigt |
|
ConfirmedByUser |
wird überprüft |
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessages:
|
RequestMessage |
Description |
|---|---|
|
CopyCantBeRetrievedFromBibPlus |
Exemplar kann nicht aus BIBLIOTHECA ausgelesen werden |
|
CopyCantBeReserved |
Exemplar kann nicht vorbestellt werden |
|
ReminderLevelExceeded |
Maximale Mahnstufe des Benutzerkontos erreicht |
|
AgeCheckFailed |
Exemplar kann aufgrund der Altersbeschränkung nicht vorbestellt werden |
|
ReservationLimitExceeded |
Maximale Anzahl von Vorbestellungen auf dem Benutzerkonto erreicht |
|
FeeLimitExceeded |
Maximale Gebührengrenze erreicht |
|
InvalidCopyStatusForReservation |
Exemplar nicht vorbestellbar |
|
NoReservableCopyFound |
Kein vorbestellbares Exemplar gefunden |
|
NoReservationDuplicateRequestCatalogueReserved |
Medium bereits vom Leser vorbestellt |
|
NoReservationDuplicateRequestCopyReserved |
Exemplar bereits vom Leser vorbestellt |
|
NoReservationDuplicateRequestCatalogueLoaned |
Medium bereits vom Leser ausgeliehen |
|
NoReservationDuplicateRequestCopyLoaned |
Exemplar bereits vom Leser ausgeliehen |
Functions
GET a single ReservationRequest
Liefert eine offene Vormerkungsanfrage des aktuellen Benutzers.
Result
LoanReservationRequest
GET /reservationrequests/{id}
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
id |
String |
ID der Vorbestellungsanfrage |
Example
GET https://localhost /OPEN/RESTv1/reservationrequests/353FDCAB22B6D94C65DF9BA9C3CC5A24?APIKey=[***] HTTP/1.1
Add a ReservationRequest
Erstellt eine neue Vormerkungsanfrage.
Result
Array<LoanReservationRequest>
Als Parameter wird entweder eine Liste von Exemplarnummern oder eine Liste von Mediennummern erwartet.
POST /reservationrequests/{catalogueid_or_cataloguecopyid}
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
PickupLocationId |
String |
3 |
Kürzel der Abholzweigstelle |
|
CatalogueIds |
String |
15 |
Mediennummern der vorzumerkenden Werke (optional) |
|
CatalogueCopyIds |
String |
15 |
Exemplarnummern der vorzumerkenden Werke (optional) |
Example
POST https://localhost /OPEN/RESTv1/reservationrequests?APIKey=[***]&pickuplocationid=00&cataloguecopyids=0143236001 HTTP/1.1
Comfirm a ReservationRequest
Bestätigt eine Vormerkungsanfrage.
Result
LoanReservationRequest
PUT /reservationrequests/{id}
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
id |
String |
ID der Vorbestellungsanfrage |
Example
PUT https://localhost /OPEN/RESTv1/reservationrequests/353FDCAB22B6D94C65DF9BA9C3CC5A24?APIKey=[***] HTTP/1.1
RegistrationRequests
Durchführen von Registrierungen
Erzeugt einen Leser mit den angegebenen Daten.
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header.
Enkodierung des Bodys ist UTF-8.
Werden maximal erlaubte Längen für Felder überschritten, so wird die Registrierung dennoch durchgeführt und die Werte werden jeweils auf die maximale Länge abgeschnitten.
Data Types
RegistrationRequest
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
AccountNumber |
String |
15 |
Ausweisnummer |
|
Password |
String |
88 |
Passwort |
|
UserGroupId |
String |
3 |
Kürzel der Benutzergruppe |
|
BranchId(*) |
String |
3 |
Kürzel der Zweigstelle |
|
AccountContact |
Contact |
Kontaktinformationen |
|
|
LegalGuardianContact(*) |
Contact |
Erziehungsberechtigter |
(*) Optional
Contact
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
Sex |
String |
Geschlecht |
|
|
Salutation(*) |
String |
50 |
Titel/Anrede |
|
FirstName |
String |
248 |
Vorname |
|
LastName |
String |
248 |
Nachname |
|
DateOfBirth(**) |
String |
10 |
Geburtsdatum |
|
Address |
String |
248 |
Straße Hausnummer |
|
City |
String |
40 |
Ort |
|
PostalCode |
String |
10 |
PLZ |
|
Email(*)(**) |
String |
80 |
E-Mail-Adresse |
|
PhoneNumber(*) |
String |
20 |
Festnetznummer |
|
MobileNumber(*)(**) |
String |
30 |
Mobilfunknummer |
(*) Optional (**) Not supported for RegistrationRequest.LegalGuardianContact
Werte von Sex:
|
Sex |
Description |
|---|---|
|
Female |
Weiblich |
|
Male |
Männlich |
|
Diverse |
Divers |
|
Institution |
Institution |
|
NotSpecified |
Ohne Angabe |
RegistrationResponse
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessage:
|
RequestMessage |
Description |
|---|---|
|
PatronAccountAlreadyExists |
Ausweisnummer ist bereits vergeben |
|
InvalidParameters |
Parameter ungültig. Gefolgt von Invalid:Parametername |
Functions
Add a RegistrationRequest
Erstellt eine neue Registrierungsanfrage
Result
RegistrationResponse
POST /registrationrequests
Parameters
None
Body
RegistrationRequest
Example
POST /registrationrequests?APIKey=[***] HTTP/1.1
Authorization: Basic T1BFTkFQSTpzZWNyZXQ=
Content-Type: application/json
{
"AccountNumber":"12345678",
"Password":"password",
"UserGroupId":"ERW",
"AccountContact":{
"Sex":"Male",
"FirstName":"Test",
"LastName":"User",
"Address":"Street 1",
" City":"Speyer",
"PostalCode":"67346",
"Email":aemail@provider.com,
"MobileNumber":"015112345678"
}
}
PatronAccountRenewal-Requests
D urchführen von Verlängerungen des Ausweises
Um die Optionen der Verlängerung in Form von PatronAccountRenewalRequests abzufragen, wird POST verwendet. Der Response enthält maximal drei Optionen.
Werden keine Optionen geliefert, so ist eine Verlängerung für den Ausweis ist nicht möglich.
Um eine der Verlängerungsoptionen anzuwenden, wird ein PUT mit der entsprechenden ID verwendet. Ist diese erfolgreich, so ist der RequestState in der Antwort Accepted.
Der Benutzer wird über die mit dem Header zu sendende Autorisierungsinformation (Username sowie passendes Password) ermittelt.
Data Types
PatronAccountRenewalRequest
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Verlängerungsanfrage |
|
RequestState |
String |
Ergebnis der Anfrage |
|
RequestMessages |
List<String> |
Statusmeldungen zu Verlängerungsanfragen |
|
IntervalType |
String |
Intervallart |
|
IntervalValue |
Int |
Intervallwert |
|
NewValidDate |
String |
Neues Gültigkeitsdatum |
|
Fee |
Decimal |
Gebühr |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Unconfirmed |
Unbestätigt |
|
ConfirmedByUser |
wird überprüft |
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessages:
|
RequestMessage |
Description |
|---|---|
|
InvalidPatronAccountExtensionParameter |
Anfrage nicht gültig. Bsp.: Keine Benutzerdaten übergeben. |
|
FeeLimitExceeded |
Maximale Gebührengrenze erreicht |
|
ReminderLevelExceeded |
Maximale Mahnstufe des Benutzerkontos erreicht |
|
RequestIsRejected |
Ein Request, der abgewiesen ist, kann nicht bestätigt werden. |
|
AccountDisabled |
Der Ausweis ist gesperrt. |
Functions
Add a PatronAccountRenewalRequest
Erstellt eine neue Verlängerungsanfrage.
Result
List<PatronAccountRenewalRequests>
POST /patronaccountrenewalrequests
Parameters
None
Example
POST /patronaccountrenewalrequests?APIKey=[***] HTTP/1.1
Confirm a PatronAccountRenewalRequest
Bestätigt eine neue Verlängerungsanfrage.
Result
PatronAccountRenewalRequests
PUT / patronaccountrenewalrequests/{id}
Parameters
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Anfrage |
Example
PUT /patronaccountrenewalrequests/{id}?APIKey=[***] HTTP/1.1
Get all PatronAccountRenewalRequests
Liefert bereits angefragte, noch gültige Verlängerungsanfragen.
Result
List<PatronAccountRenewalRequests>
GET / patronaccountrenewalrequests
Parameters
None
Example
GET /patronaccountrenewalrequests?APIKey=[***] HTTP/1.1
PatronCardChangeRequests
Setzen der Gültigkeit
Setzt die Gültigkeit des Leserausweis (Gültig bis). Um das Feld zu leeren, muss das Feld leer angegeben werden.
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header.
Enkodierung des Bodys ist UTF-8.
Data Types
PatronCardChange Request
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
AccountNumber |
String |
15 |
Leserausweis-Nummer |
|
CardValidTill |
String |
10 |
Gültigkeit Leserausweis |
PatronCardChangeResponse
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessage:
|
RequestMessage |
Description |
|---|---|
|
InvalidParameters |
Parameter ungültig oder Änderung nicht möglich. Gefolgt von Invalid:Parametername |
Functions
Add a PatronCardChangeRequest
Erstellt eine neue Anfrage zum Setzen der Gültigkeit des Leserausweis.
Result
PatronCardChangeResponseDto
POST /patroncardchangerequests
Parameters
None
Examples
Gültigkeit des Leserausweis setzen:
POST /patroncardchangerequests?APIKey=[***] HTTP/1.1
{
„AccountNumber“: „accountNumber“,
„CardValidTill ":"2025-12-01"
}
Gültigkeit des Leserausweis entfernen:
POST / patroncardchangerequests?APIKey=[***] HTTP/1.1
{
„AccountNumber“: „accountNumber“,
„CardValidTill“: “”
}
PatronChangeRequests
Ändern von Benutzerdaten
Ändert einen Leser mit den angegebenen Daten. Um Felder zu leeren, muss das Feld leer angegeben werden. Wird der Erziehungsberechtigte leer angegeben, wird dieser komplett entfernt. Felder, die nicht geändert werden sollen, dürfen nicht angegeben werden.
Die Autorisierung erfolgt über den Benutzer im Authorization-Header.
Enkodierung des Bodys ist UTF-8.
Werden maximal erlaubte Längen für Felder überschritten, so wird die Änderung dennoch durchgeführt und die Werte werden jeweils auf die maximale Länge abgeschnitten.
Data Types
PatronChangeRequest
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
AccountNumber(*) |
String |
15 |
Ausweisnummer |
|
Password(*) |
String |
88 |
Passwort |
|
UserGroupId(*) |
String |
3 |
Kürzel der Benutzergruppe |
|
BranchId(*) |
String |
3 |
Kürzel der Zweigstelle |
|
AccountContact(*) |
Contact |
Kontaktinformationen |
|
|
LegalGuardianContact(*) |
Contact |
Erziehungsberechtigter |
(*) Optional
Contact
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
Sex(*) |
String |
Siehe Tabelle |
Geschlecht |
|
Salutation(*) |
String |
50 |
Titel |
|
FirstName(*) |
String |
248 |
Vorname |
|
LastName(*) |
String |
248 |
Nachname |
|
DateOfBirth(**) |
String |
10 |
Geburtsdatum |
|
Address(*) |
String |
248 |
Straße Hausnummer |
|
City(*) |
String |
40 |
Ort |
|
PostalCode(*) |
String |
10 |
PLZ |
|
Email(*)(**) |
String |
80 |
E-Mail-Adresse |
|
PhoneNumber(*) |
String |
20 |
Festnetznummer |
|
MobileNumber(*)(**) |
String |
30 |
Mobilfunknummer |
(*) Optional (**) Not supported for PatronChangeRequest.LegalGuardianContact
Werte von Sex:
|
Sex |
Description |
|---|---|
|
Female |
Weiblich |
|
Male |
Männlich |
|
Diverse |
Divers |
|
Institution |
Institution |
|
NotSpecified |
Ohne Angabe |
PatronChangeResponse
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessage:
|
RequestMessage |
Description |
|---|---|
|
PatronAccountAlreadyExists |
Ausweisnummer ist bereits vergeben |
|
InvalidParameters |
Parameter ungültig oder Änderung nicht möglich. Gefolgt von Invalid:Parametername (z.B. Invalid:Password oder Invalid: AccountContact.LastName - wenn der Nachname leer ist) |
|
PatronChangeRequestEmpty |
Keine Änderungen gefunden |
Functions
Add a PatronChangeRequest
Erstellt eine neue Benutzeränderungssanfrage.
Result
PatronChangeResponse
POST /patronchangerequests
Parameters
None
Example s
Passwort ändern:
POST /patronchangerequests?APIKey=[***] HTTP/1.1
{
"Password":"myNewSecurePassword!",
}
Erziehungsberechtigten entfernen:
POST /patronchangerequests?APIKey=[***] HTTP/1.1
{
"LegalGuardianContact":{}
}
E-Mail-Adresse entfernen:
POST /patronchangerequests?APIKey=[***] HTTP/1.1
{
"AccountContact":
{
"Email":""
}
E-Mail-Adresse ändern:
POST /patronchangerequests?APIKey=[***] HTTP/1.1
{
"AccountContact":
{
"Email":neu@mail.de
}
}
PatronSearchRequests
Suche von Benutzern
Es müssen alle Felder ausgefüllt werden. Es handelt sich um eine „UND“-verknüpfte Suche.
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header.
Enkodierung des Bodys ist UTF-8.
Data Types
PatronSearchRequest
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
FirstName |
String |
248 |
Vorname |
|
LastName |
String |
248 |
Nachname |
|
DateOfBirth |
String |
10 |
Geburtsdatum |
PatronSearchResponse
|
Name |
Type |
Description |
|---|---|---|
|
Count |
Int |
Anzahl von Treffern |
Functions
Add a PatronSearchRequest
Suche nach Benutzer.
Result
PatronSearchResponse
POST /PatronSearchRequests
Parameters
None
Example s
POST /patronsearchrequests?APIKey=[***] HTTP/1.1
{
"FirstName":"Vorname",
"LastName":"Name",
"DateOfBirth":"2017-01-20"
}
PatronPasswordResetRequests
Zurücksetzen von Passwörtern
Zuerst muss ein Zurücksetzungscode angefordert werden (Add). Der Prozess sieht vor, dass dieser Code an den Benutzer über die mitgelieferte mit dem Benutzer verknüpfte E-Mail-Adresse übermittelt wird. Der Benutzer bestätigt den Erhalt, indem er den Code in die Anwendung eingibt. Dies kann z.B. über einen Link geschehen. Aus Sicht der API folgt nach der Übermittlung des Codes dann der Aufruf der Bestätigung (Confirm).
Generierte Codes sind einmal verwendbar (sofern Passwortänderung erfolgreich) und laufen nach 10 Minuten automatisch ab.
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header.
Enkodierung des Bodys ist UTF-8.
Data Types
PatronPasswordResetRequest
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
Login |
String |
80 |
Ausweisnummer oder E-Mail-Adresse des Benutzers |
PatronPasswordResetRequestResponse
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
|
ResetCode |
String |
Code für das Zurücksetzen des Passwortes |
|
|
String |
E-Mail-Adresse des Benutzers |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Unconfirmed |
Unbestätigt |
|
Rejected |
Abgewiesen |
Werte von RequestMessage:
|
RequestMessage |
Description |
|---|---|
|
EmailOrCardnumberWrong |
Ausweisnummer unbekannt. E-Mail-Adresse unbekannt oder nicht eindeutig. |
PatronPasswordResetConfirm
|
Name |
Type |
Description |
|---|---|---|
|
ResetCode |
String |
Code für das Zurücksetzen des Passwortes |
|
Password |
String |
Neues Passwort |
PatronPasswordResetConfirmResponse
|
Name |
Type |
Description |
|---|---|---|
|
RequestState |
String |
Ergebnis |
|
RequestMessages |
List<String> |
Statusmeldungen |
Werte von RequestState:
|
RequestState |
Description |
|---|---|
|
Accepted |
Akzeptiert |
|
Rejected |
Abgewiesen |
Werte von RequestMessage:
|
RequestMessage |
Description |
|---|---|
|
ResetCodeInvalid |
ResetCode ist nicht (mehr) gültig. |
|
InvalidParameters |
Parameter ungültig oder Änderung nicht möglich. Gefolgt von Invalid:Parametername (z.B. Invalid:Password) |
Functions
Add a PatronPasswordResetRequests
Initiieren des Zurücksetzens des Passwortes.
Result
PatronPasswordResetRequestResponse
POST /PatronPasswordResetRequestResponse
Parameters
None
Example s
POST /patronpasswordresetrequests?APIKey=[***] HTTP/1.1
{
"Login":"1234567"
}
POST /patronpasswordresetrequests?APIKey=[***] HTTP/1.1
{
"Login":e@mail.de
}
Confirm a PatronPasswordResetRequests
Passwort zurücksetzen.
Result
PatronPasswordResetConfirmResponse
PUT /PatronPasswordResetRequestResponse
Parameters
None
Example s
PUT /patronpasswordresetrequests?APIKey=[***] HTTP/1.1
{
"ResetCode":"abcde….." ,
"Password":"NewPassword"
}
PickupBranches
Abfrage von Zweigstellen
Ressource für das Ermitteln aller Zweigstellen einer Bibliothek sowie der Abholzweigstelle(n) eines Lesers.
Data Types
LocationInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Zweigstelle |
|
Description |
String |
Name der Zweigstelle |
Functions
GET all PickupBranches
Liefert alle Zweigstellen.
Diese Funktion wird abgelöst durch:
GET /branches
Result
Array<LocationInformation>
GET /pickupbranches
Example
GET https://localhost/OPEN/RESTv1/pickup...s?APIKey=[***] HTTP/1.1
GET PickupBranches by Patron
Liefert alle Abholzweigstellen eines Lesers.
Result
Array<LocationInformation>
GET /pickupbranches
Parameters
|
Name |
Type |
Länge |
Description |
|---|---|---|---|
|
PatronAccountId |
String |
15 |
Leserausweis-Nummer |
Example
GET https://localhost /OPEN/RESTv1/pickupbranches?APIKey=[***]&patronaccountid=07005311 HTTP/1.1
Fees
Unpaid
Abfrage von offenen Gebühren aller Benutzer
Die Autorisierung erfolgt über den Systembenutzer im Authorization-Header.
Data Types
UnpaidFeesResponse
|
Name |
Type |
Description |
|---|---|---|
|
UnpaidFees |
List<UnpaidFees> |
Liste von UnpaidFees |
UnpaidFees
|
Name |
Type |
Description |
|---|---|---|
|
AccountNumber |
String |
Ausweisnummer |
|
Fees |
List<Fee> |
Liste an unbezahlten Gebühren |
Fee
|
Name |
Type |
Description |
|---|---|---|
|
CatalogueId |
String |
BIBLIOTHECA Medien-Nummer (wenn es sich um eine medienbezogene Gebühr handelt) |
|
Amount |
Decimal |
Betrag |
|
Description |
String |
Beschreibung der Kostenart (z.B. Verlängerung, Vormerkung, Ausweisverlängerung) |
|
Id |
Number |
Id der Gebühr |
Functions
GET Unpaid
Liefert alle offenen Gebühren aller Benutzer.
Result
UnpaidFeesResponse
GET /fees/unpaid
Example
GET https://localhost/OPEN/RESTv1/fees/u...d?APIKey=[***] HTTP/1.1
Authorization: Basic T1BFTkFQSTpzZWNyZXQ=
Result
{
"UnpaidFees": [
{
"AccountNumber": "12345678",
"Fees": [
{
"Amount": 1.23,
"CatalogueId": "123",
"Description": "Leihgebühr CD",
"Id": 1001
},
{
"Amount": 10,
"CatalogueId": null,
"Description": "Ausweisverlängerung 1 Jahr",
"Id": 1002
}
]
},
{
"AccountNumber": "23456789",
"Fees": [
{
"Amount": 1.25,
"CatalogueId": "12304",
"Description": "Verlängerungsgebühr (neue Frist 24.12.2019)",
"Id": 1033
}
]
}
]
}
Branches
Abfrage von Zweigstellen
Ressource für das Ermitteln aller Zweigstellen einer Bibliothek.
Data Types
LocationInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Zweigstelle |
|
Description |
String |
Name der Zweigstelle |
Functions
GET all Branches
Liefert alle Zweigstellen.
Result
Array<LocationInformation>
GET /branches
Example
GET https://localhost /OPEN/RESTv1/branches?APIKey=[***] HTTP/1.1
Copystatuses
Abfrage von allen Exemplarstatus
Ressource für das Ermitteln aller Exemplarstatus einer Bibliothek.
Data Types
CopyStatusInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID des Exemplarstatus |
|
Description |
String |
Name des Exemplarstatus |
Functions
GET all CopyStatuses
Liefert alle Exemplarstatus.
Result
Array<CopyStatusInformation>
GET /copystatuses
Example
GET https://localhost /OPEN/RESTv1/ copystatuses?APIKey=[***] HTTP/1.1
MediaGroups
Abfrage von allen Mediengruppen
Ressource für das Ermitteln aller Mediengruppen einer Bibliothek.
Data Types
MediaGroupInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Mediengruppe |
|
Description |
String |
Name der Mediengruppe |
Functions
GET all MediaGroups
Liefert alle Mediengruppen.
Result
Array<MediaGroupInformation>
GET /mediagroups
Example
GET https://localhost /OPEN/RESTv1/ mediagroups?APIKey=[***] HTTP/1.1
UserGroups
Abfrage von allen Benutzergruppen
Ressource für das Ermitteln aller Benutzergruppen einer Bibliothek.
Data Types
UserGroupInformation
|
Name |
Type |
Description |
|---|---|---|
|
Id |
String |
ID der Benutzergruppe |
|
Description |
String |
Name der Benutzergruppe |
Functions
GET all UserGroups
Liefert alle Exemplarstatus.
Result
Array<UserGroupInformation>
GET /usergroups
Example
GET https://localhost /OPEN/RESTv1/ usergroups?APIKey=[***] HTTP/1.1