# CareLit OPAC API

Basis-URL: `https://app.carelit.de/opac`

Die OPAC-API ist eine read-only Metadaten-Schnittstelle. Sie ist fuer Bibliotheken, Discovery-Systeme, Moodle-Kursraeume und Drittsysteme gedacht. Lizenzpflichtige PDF-Downloads und Volltexte werden nicht ausgeliefert.

## Authentifizierung

Alle produktiven Endpunkte erfordern einen API-Key. Keys werden in CareLit unter
`Setup -> API-Keys` erzeugt und koennen dort jederzeit widerrufen werden.

Empfohlen ist die Uebergabe per Header:

```http
X-API-Key: cl_live_...
```

oder:

```http
Authorization: Bearer cl_live_...
```

Fuer OpenSearch-Templates, einfache Portale oder iframe-Widgets kann der Key
auch als Query-Parameter uebergeben werden:

```http
GET /opac/api?endpoint=search&q=Delir&api_key=cl_live_...
```

Hinweis: Header sind fuer Server-zu-Server-Integrationen vorzuziehen, weil Query-Parameter eher in Logs oder Browser-Verlaeufen sichtbar werden.

## REST/JSON

### Suche

```http
GET /opac/api?endpoint=search&q=Sturzprävention&limit=10
X-API-Key: cl_live_...
```

Parameter:

| Parameter | Bedeutung |
| --- | --- |
| `q` / `query` | Freitextsuche |
| `journal` | Zeitschriftentitel |
| `author` | Autor:in |
| `issn` | ISSN |
| `doi` | DOI oder DOI-Teil |
| `zsid` | interne Zeitschriften-ID |
| `year` | Jahr exakt |
| `from` / `until` | Jahr von/bis |
| `has_fulltext` | `1` oder `0` |
| `has_pdf` | `1` oder `0` |
| `limit` | Trefferanzahl, Standard 20, Maximum per Config |
| `offset` | Offset fuer Paging |
| `page` | Alternative zu Offset |
| `sort` | `relevance`, `newest`, `oldest`, `journal`, `title`, `rank` |

Antwort:

```json
{
  "ok": true,
  "meta": { "service": "CareLit OPAC API" },
  "query": { "q": "Sturzprävention", "offset": 0, "limit": 10, "total": 604 },
  "items": [
    {
      "id": 581779,
      "identifier": "oai:carelit:581779",
      "type": "article",
      "title": "Erträge steigern mit rehabilitativer Pflege",
      "authors": ["Heckelmann, M.", "Lamelas, B."],
      "journal": { "title": "Altenheim", "issn": "0002-6573" },
      "issued": { "year": "2026", "issue": "4", "pages": "27 bis 30" },
      "availability": {
        "pdf_available": true,
        "download_url": null,
        "note": "Die OPAC-Schnittstelle liefert Metadaten und keine lizenzpflichtigen PDF-Downloads."
      }
    }
  ]
}
```

### Einzeldatensatz

```http
GET /opac/api?endpoint=record&id=581779
X-API-Key: cl_live_...
```

### Suggestions

```http
GET /opac/api?endpoint=suggest&q=Delir
GET /opac/suggest?q=Delir
```

`/opac/suggest` liefert das OpenSearch-Suggestions-Format:

```json
["Delir", ["Delirprävention"], ["title"], ["https://..."]]
```

### Status und Formate

```http
GET /opac/api?endpoint=status
GET /opac/api?endpoint=formats
```

## Export

Einzeldatensatz:

```http
GET /opac/export?id=581779&format=ris
GET /opac/export?id=581779&format=bibtex
GET /opac/export?id=581779&format=csl-json
GET /opac/export?id=581779&format=dc
GET /opac/export?id=581779&format=marcxml
```

Trefferliste exportieren:

```http
GET /opac/export?q=Delir&limit=25&format=ris
```

Mehrere IDs:

```http
GET /opac/export?ids=581779,581778,581777&format=bibtex
```

## OpenSearch

```http
GET /opac/opensearch.xml
```

Geeignet fuer einfache Suchboxen in Portalen oder Moodle-Blöcken.

## SRU 1.2

Explain:

```http
GET /opac/sru?operation=explain
```

SearchRetrieve:

```http
GET /opac/sru?operation=searchRetrieve&version=1.2&query=Sturzprävention&maximumRecords=10
GET /opac/sru?operation=searchRetrieve&query=dc.creator="Klie"&recordSchema=dc
GET /opac/sru?operation=searchRetrieve&query=dc.title="Delir"&recordSchema=marcxml
```

Unterstuetzte Schemata: `dc`, `marcxml`.

## OAI-PMH 2.0

```http
GET /opac/oai?verb=Identify
GET /opac/oai?verb=ListMetadataFormats
GET /opac/oai?verb=ListSets
GET /opac/oai?verb=GetRecord&identifier=oai:carelit:581779&metadataPrefix=oai_dc
GET /opac/oai?verb=ListRecords&metadataPrefix=oai_dc&from=2026-01-01&limit=50
GET /opac/oai?verb=ListIdentifiers&metadataPrefix=marcxml&limit=50
```

ResumptionToken:

```http
GET /opac/oai?verb=ListRecords&metadataPrefix=oai_dc&resumptionToken=50:50
```

## Fehlerformat

REST-Endpunkte liefern bei Fehlern:

```json
{
  "ok": false,
  "error": "not_found",
  "message": "Dokument nicht gefunden."
}
```

## Datenschutz und Lizenz

- Keine PDF-URLs.
- Keine direkten Volltexte.
- `availability.pdf_available` darf fuer Bestands-/Resolverlogik genutzt werden, loest aber keinen Download aus.
- Detail-Links zeigen auf CareLit und respektieren dort die normalen Rechte.