Zum Inhalt

REST API

Die Librario REST API ermöglicht Ihnen die programmatische Integration und Automatisierung Ihrer Bibliotheksprozesse. Sie können damit alle wichtigen Funktionen von Librario in Ihre bestehende IT-Infrastruktur bzw. in Ihre Prozesse einbinden.

Kein Web Scraping

Bitte verwenden Sie für automatisierte Zugriffe ausschließlich die REST API. Das Scraping der Weboberfläche wird nicht unterstützt und kann zu unerwarteten Fehlern führen. Die API bietet alle notwendigen Endpunkte für eine programmatische Integration.

Zugriff auf die API

Die API ist unter folgender URL erreichbar:

https://<ihre-firma>.mylibrar.io/api, zum Beispiel: https://app.mylibrar.io/api

Falls Sie eine eigene Subdomain zugewiesen bekommen haben, können Sie diese in der URL verwenden.

API-Dokumentation

Screenshot der Swagger UI Dokumentation der Librario API. Links sind die verschiedenen API-Endpunkte nach Ressourcen gruppiert zu sehen. Rechts werden die Details des ausgewählten Endpunkts mit Parametern und Beispielantworten angezeigt.

Die interaktive API-Dokumentation mittels Swagger UI

Die vollständige API-Dokumentation steht Ihnen in zwei Formaten zur Verfügung:

  1. Swagger UI: Eine interaktive Web-Oberfläche zum Erkunden der API

    • Erreichbar unter https://<ihre-firma>.mylibrar.io/api
    • Ermöglicht das direkte Testen von API-Aufrufen
    • Zeigt Beispielanfragen und -antworten
    • Bietet Download der OpenAPI-Spezifikation als swagger.yaml

  2. OpenAPI-Spezifikation (swagger.yaml): Eine maschinenlesbare Beschreibung der API

    • Basis für die automatische Generierung von API-Clients
    • Kann in API-Entwicklungswerkzeuge importiert werden
    • Hilfreich für die Verwendung mit KI-Tools wie ChatGPT oder Claude

Authentifizierung

Die API verwendet Basic Authentication für den Zugriff. Alle Personen können sich mit ihren normalen Librario-Zugangsdaten an der API anmelden. Die Berechtigungen entsprechen dabei den in der Anwendung konfigurierten Rollen.

Technische Benutzer für Integrationen

Es wird empfohlen, für automatisierte Prozesse dedizierte technische Zugänge anzulegen. Dies macht die Integration unabhängig von personenbezogenen Accounts und vereinfacht die Verwaltung von Zugriffsrechten.

Datenformat

Die API nutzt das JSON-Format für den Datenaustausch. Dieses Format ist in allen gängigen Programmiersprachen einfach zu verarbeiten.

Paginierung

Bei Listen-Endpoints wird die Ausgabe auf 25 Einträge pro Seite begrenzt. Um alle Datensätze zu erhalten, müssen Sie die Seiten nacheinander abrufen.

Die Navigation wird durch spezielle Response-Header erleichtert:

  • X-Total: Gesamtanzahl der verfügbaren Einträge
  • Link: URLs für erste/vorherige/nächste/letzte Seite

Der Link Header macht die Implementierung besonders einfach: Solange ein next Link vorhanden ist, gibt es weitere Seiten abzurufen.

Typische Anwendungsfälle

Die folgenden Beispiele zeigen die API-Nutzung mit zwei verschiedenen Ansätzen:

  • curl als einfaches Kommandozeilen-Tool für schnelle Tests und Debugging
  • Ruby mit der eingebauten Net::HTTP Bibliothek für Produktiv-Implementierungen

Benutzer:innen-Management

In vielen Organisationen soll der Lebenszyklus von Benutzerkonten automatisiert werden, etwa wenn neue Mitarbeitende eingestellt werden oder das Unternehmen verlassen.

# Neue:n Benutzer:in anlegen
curl -X POST "https://ihre-firma.mylibrar.io/api/v2/users" \
  -u "tech_user@example.com:password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "max.mustermann@example.com",
    "name": "Max Mustermann",
    "roles": ["librarian"]
  }'

# Rollen zuweisen
curl -X PATCH "https://ihre-firma.mylibrar.io/api/v2/users/123/roles" \
  -u "tech_user@example.com:password" \
  -H "Content-Type: application/json" \
  -d '{"roles": ["admin", "librarian"]}'

# Benutzer:in löschen
curl -X DELETE "https://ihre-firma.mylibrar.io/api/v2/users/123" \
  -u "tech_user@example.com:password"
user-management.rb
require 'net/http'
require 'json'
require 'uri'

class LibrarioClient
  def initialize(host:, username:, password:)
    @host = host
    @username = username
    @password = password
  end

  def create_user(email:, name:, roles: [])
    # Neue:n Benutzer:in anlegen
    post('/users', {
      email: email,
      name: name,
      roles: roles
    })
  end

  def assign_roles(user_id:, roles:)
    # Rollen zuweisen/aktualisieren
    patch("/users/#{user_id}/roles", {
      roles: roles
    })
  end

  def delete_user(user_id:)
    # Benutzer:in löschen bei Austritt
    delete("/users/#{user_id}")
  end

  private

  def request(method, path, data = nil)
    uri = URI("https://#{@host}/api/v2#{path}")

    # Request vorbereiten
    request = case method
    when :get    then Net::HTTP::Get.new(uri)
    when :post   then Net::HTTP::Post.new(uri)
    when :patch  then Net::HTTP::Patch.new(uri)
    when :delete then Net::HTTP::Delete.new(uri)
    end

    # Auth & Headers setzen
    request.basic_auth(@username, @password)
    request['Content-Type'] = 'application/json'
    request.body = data.to_json if data

    # Request ausführen
    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    JSON.parse(response.body) unless response.body.empty?
  end

  def post(path, data)   ; request(:post, path, data)   ; end
  def patch(path, data)  ; request(:patch, path, data)  ; end
  def delete(path)       ; request(:delete, path)       ; end
end

# Verwendung:
client = LibrarioClient.new(
  host: 'ihre-firma.mylibrar.io',
  username: 'tech_user@example.com',
  password: 'password'
)

client.create_user(
  email: "max.mustermann@example.com",
  name: "Max Mustermann",
  roles: ["librarian"]
)

Datenimport

Beim Umstieg auf Librario müssen oft Daten aus dem Altsystem migriert werden. Die API ermöglicht einen strukturierten Import:

curl -X POST "https://ihre-firma.mylibrar.io/api/v2/publications" \
  -u "tech_user@example.com:password" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Beispiel-Publikation",
    "authors": [
      {"name": "Max Mustermann", "type": "person"}
    ],
    "publishable_type": "Book",
    "isbn": "978-3-86680-192-9"
  }'
datenimport.rb
require 'net/http'
require 'json'
require 'uri'
require 'mime-types'

class LibrarioImport
  def initialize(host:, username:, password:)
    @host = host
    @username = username
    @password = password
  end

  def import_publication(data)
    uri = URI("https://#{@host}/api/v2/publications")

    # Request vorbereiten
    request = Net::HTTP::Post.new(uri)
    request.basic_auth(@username, @password)
    request['Content-Type'] = 'application/json'
    request.body = data.to_json

    # Request ausführen
    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    if response.is_a?(Net::HTTPSuccess)
      publication = JSON.parse(response.body)
      puts "Importiert: #{data[:title]} (ID: #{publication['id']})"
      publication
    else
      puts "Fehler bei #{data[:title]}: #{response.body}"
      nil
    end
  end

  def attach_file(publication_id:, file_path:, name: nil)
    # Mime-Type ermitteln
    mime_type = MIME::Types.type_for(file_path).first&.content_type || 'application/pdf'
    file_name = File.basename(file_path)
    display_name = name || file_name

    # Presigned URL anfordern
    presign_data = get_presigned_url(filename: file_name, type: mime_type)
    return nil unless presign_data

    # Datei hochladen
    uploaded = upload_file(
      url: presign_data['url'],
      fields: presign_data['fields'],
      file_path: file_path,
      content_type: mime_type
    )
    return nil unless uploaded

    # Asset erstellen
    asset = create_asset(
      publication_id: publication_id,
      name: display_name,
      content_type: mime_type,
      file: {
        id: presign_data['fields']['key'],
        storage: 'cache',
        metadata: {
          filename: file_name,
          size: File.size(file_path),
          mime_type: mime_type
        }
      }
    )

    if asset
      puts "Datei '#{display_name}' erfolgreich angehängt"
      asset
    else
      puts "Fehler beim Anhängen der Datei '#{display_name}'"
      nil
    end
  end

  private

  def get_presigned_url(filename:, type:)
    uri = URI("https://#{@host}/api/v2/assets/presign")
    uri.query = URI.encode_www_form(
      filename: filename,
      type: type
    )

    request = Net::HTTP::Get.new(uri)
    request.basic_auth(@username, @password)

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    if response.is_a?(Net::HTTPSuccess)
      JSON.parse(response.body)
    else
      puts "Fehler beim Anfordern der Upload-URL: #{response.body}"
      nil
    end
  end

  def upload_file(url:, fields:, file_path:, content_type:)
    uri = URI(url)

    # Multipart POST Request vorbereiten
    request = Net::HTTP::Post.new(uri)
    boundary = "LibrarioImportBoundary#{rand(1000000)}"
    request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"

    # Request Body zusammenbauen
    body = []

    # Presigned Felder hinzufügen
    fields.each do |key, value|
      body << "--#{boundary}\r\n"
      body << "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n"
      body << "#{value}\r\n"
    end

    # Datei hinzufügen
    body << "--#{boundary}\r\n"
    body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{File.basename(file_path)}\"\r\n"
    body << "Content-Type: #{content_type}\r\n\r\n"
    body << File.read(file_path)
    body << "\r\n--#{boundary}--\r\n"

    request.body = body.join

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    if response.is_a?(Net::HTTPSuccess)
      true
    else
      puts "Fehler beim Hochladen der Datei: #{response.body}"
      false
    end
  end

  def create_asset(publication_id:, name:, content_type:, file:)
    uri = URI("https://#{@host}/api/v2/assets")

    request = Net::HTTP::Post.new(uri)
    request.basic_auth(@username, @password)
    request['Content-Type'] = 'application/json'
    request.body = {
      publication_id: publication_id,
      name: name,
      content_type: content_type,
      file: file
    }.to_json

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    if response.is_a?(Net::HTTPSuccess)
      JSON.parse(response.body)
    else
      puts "Fehler beim Erstellen des Assets: #{response.body}"
      nil
    end
  end
end

# Initialize importer
importer = LibrarioImport.new(
  host: 'ihre-firma.mylibrar.io',
  username: 'tech_user@example.com',
  password: 'password'
)

# Create publication
publication = importer.import_publication(
  title: "Beispiel-Publikation",
  authors: [
    {name: "Max Mustermann", type: "person"}
  ],
  publishable_type: "Book",
  isbn: "978-3-86680-192-9"
)

# Attach PDF file if publication was created successfully
if publication
  importer.attach_file(
    publication_id: publication['id'],
    file_path: '/path/to/document.pdf',
    name: 'Volltext' # Optional display name
  )
end

Automatischer Abgleich von Publikationslisten

Ein häufiges Szenario ist der Abgleich von EndNote-Exporten mit dem Librario-Bestand. Dabei soll ermittelt werden, welche Publikationen bereits verfügbar sind und welche noch beschafft werden müssen.

# Einzelne DOI prüfen
curl -G "https://ihre-firma.mylibrar.io/api/v2/publications" \
  -u "tech_user@example.com:password" \
  --data-urlencode "doi=10.1234/example.doi"
Voraussetzungen für die Input-Datei
  • CSV-Datei mit UTF-8 Kodierung
  • Enthält eine Spalte mit dem Header "DOI"
  • Weitere Spalten werden in die Ausgabedatei übernommen

Beispiel endnote_export.csv:

DOI,Title,Authors,Year
10.1234/example.1,Example Paper 1,John Doe,2023
10.1234/example.2,Example Paper 2,Jane Smith,2022

Format der Ausgabedatei

Die Ausgabedatei availability_report.csv enthält alle Spalten der Eingabedatei plus zwei zusätzliche Spalten:

  • Status: "Verfügbar" oder "Nicht verfügbar"
  • URL: Link zur Publikation in Librario (falls verfügbar)

Beispiel availability_report.csv:

DOI,Title,Authors,Year,Status,URL
10.1234/example.1,Example Paper 1,John Doe,2023,Verfügbar,https://firma.mylibrar.io/publications/123
10.1234/example.2,Example Paper 2,Jane Smith,2022,Nicht verfügbar,

automatischer-abgleich.rb
require 'net/http'
require 'json'
require 'uri'
require 'csv'

class PublicationChecker
  def initialize(host:, username:, password:)
    @host = host
    @username = username
    @password = password
  end

  def check_publications(input_file:, output_file:)
    # Eingabe-CSV lesen
    rows = CSV.read(input_file, headers: true)

    # Für jede DOI den Status prüfen
    rows.each do |row|
      next unless row['DOI'] # Zeilen ohne DOI überspringen

      uri = URI("https://#{@host}/api/v2/publications")
      uri.query = URI.encode_www_form(doi: row['DOI'])

      # Request vorbereiten & ausführen
      request = Net::HTTP::Get.new(uri)
      request.basic_auth(@username, @password)

      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
        http.request(request)
      end

      data = JSON.parse(response.body)

      if response.is_a?(Net::HTTPSuccess) && !data['records'].empty?
        # Publikation gefunden
        pub = data['records'].first
        row['Status'] = 'Verfügbar'
        row['URL'] = "https://#{@host}/publications/#{pub['id']}"
      else
        # Nicht im Bestand
        row['Status'] = 'Nicht verfügbar'
        row['URL'] = ''
      end
    end

    # Ergebnis in neue CSV schreiben
    CSV.open(output_file, 'w') do |csv|
      csv << rows.headers # Headers inkl. neue Spalten
      rows.each { |row| csv << row }
    end
  end
end

# Verwendung
checker = PublicationChecker.new(
  host: 'ihre-firma.mylibrar.io',
  username: 'tech_user@example.com',
  password: 'password'
)

checker.check_publications(
  input_file: 'endnote_export.csv',
  output_file: 'availability_report.csv'
)

Backups und Datensicherung

Die API bietet umfassende Möglichkeiten zur Datensicherung. Ein einfaches Backup mittels /publications/all Endpunkt ermöglicht das seitenweise Abrufen aller Publikationen. Weitere Details finden Sie in der Backup-Dokumentation.

Best Practices

Rate Limiting

Um die API-Server nicht zu überlasten, beachten Sie bitte:

  • Maximale Anfragerate: 60 Anfragen pro Minute
  • Bei Listenabfragen: Paginierung verwenden
  • Große Datenmengen in kleineren Batches verarbeiten

Fehlerbehandlung

Die API verwendet folgende HTTP-Statuscodes:

  • 200: Anfrage erfolgreich
  • 401: Nicht autorisiert
  • 403: Zugriff verweigert
  • 404: Ressource nicht gefunden
  • 429: Zu viele Anfragen (Rate Limit überschritten)
  • 500: Interner Serverfehler

Fehlerantworten enthalten zusätzliche Details im JSON-Format:

{
  "error": {
    "code": "RecordNotFound",
    "message": "Requested record not found"
  }
}