OpenBookCase Entwickler-API
Baue Apps auf den OpenBookCase-Daten. Das Lesen öffentlicher Daten ist frei — kein Schlüssel nötig.
Zum Schreiben (Einträge anlegen/bearbeiten, Fotos, Wunschlisten, …) brauchst du ein OAuth-2.0-Access-Token,
das im Namen einer deiner Nutzer:innen handelt. Alle Anfragen sind JSON rein / JSON raus und liegen unter
/api/v1.
Basis-URL in der Produktion: https://openbookcase.de
So funktioniert es
- Freies Lesen: die Kartenausschnitts-Liste, einzelne Einträge sowie deren Fotos und Wunschlisten sind öffentlich — ohne Token abrufbar.
- Authentifiziertes Schreiben: jede Änderung erfolgt als eine deiner Nutzer:innen. Sie autorisieren deine App einmalig (OAuth), dein Token legt dann Daten in ihrem Namen an/bearbeitet sie.
- Keine Konto-Endpunkte: bewusst keine API für E-Mail, Passwort, Benachrichtigungen oder Kontolöschung.
- Offene Daten: der Datenbestand stammt aus OpenStreetMap und steht unter der ODbL — siehe Datenlizenz.
Zugang erhalten
Öffne Profil → API-Zugang und stelle einen Antrag, der deine App und die geplante Datennutzung beschreibt. Ein Admin prüft ihn (mit eingebautem Rückfrage-Dialog bei Fragen). Nach Freigabe erhältst du deine Zugangsdaten:
- Public Client (Mobil-/Single-Page-Apps): eine
client_id, kein Secret. Muss PKCE verwenden. - Confidential Client (Apps mit sicherem Backend): eine
client_idund einclient_secret, das einmalig angezeigt wird — sicher aufbewahren.
Außerdem hinterlegst du eine oder mehrere Redirect-URIs und wählst die benötigten Scopes.
Authentifizierung (OAuth 2.0 Authorization Code)
Zwei Endpunkte: /oauth/authorize (Nutzer:in genehmigt deine App) und
/oauth/token (du tauschst den Code gegen Tokens).
Access-Tokens gelten 1 Stunde, Refresh-Tokens 1 Jahr (bei Nutzung rotiert). Tokens bleiben gültig, bis sie widerrufen werden.
1 · Public Clients (Mobil/SPA) — PKCE
Erzeuge zuerst einen PKCE-Verifier + Challenge:
# code_verifier: 43–128 zufällige Zeichen; code_challenge = base64url(sha256(verifier))
CODE_VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" \
| openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=')
Schicke die Nutzer:in zur Authorize-URL (im Browser / In-App-Browser öffnen):
https://openbookcase.de/oauth/authorize
?response_type=code
&client_id=DEINE_CLIENT_ID
&redirect_uri=https://deineapp.example/callback
&scope=bookcases.write%20images.write
&state=ZUFALLSWERT
&code_challenge=$CODE_CHALLENGE
&code_challenge_method=S256
Nach der Zustimmung erfolgt die Weiterleitung zu
https://deineapp.example/callback?code=AUTH_CODE&state=ZUFALLSWERT.
Tausche den Code gegen Tokens (Public Clients senden den Verifier, kein Secret):
curl -X POST https://openbookcase.de/oauth/token \
-d grant_type=authorization_code \
-d client_id=DEINE_CLIENT_ID \
-d redirect_uri=https://deineapp.example/callback \
-d code_verifier=$CODE_VERIFIER \
-d code=AUTH_CODE
Antwort:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "def502..."
}
2 · Confidential Clients (mit Backend)
Gleicher Ablauf, aber Authentifizierung per Secret statt PKCE-Verifier:
curl -X POST https://openbookcase.de/oauth/token \
-d grant_type=authorization_code \
-d client_id=DEINE_CLIENT_ID \
-d client_secret=DEIN_CLIENT_SECRET \
-d redirect_uri=https://deineapp.example/callback \
-d code=AUTH_CODE
3 · Token erneuern
curl -X POST https://openbookcase.de/oauth/token \
-d grant_type=refresh_token \
-d client_id=DEINE_CLIENT_ID \
-d refresh_token=DEIN_REFRESH_TOKEN
# Confidential Clients hängen zusätzlich an: -d client_secret=DEIN_CLIENT_SECRET
Scopes
Fordere nur an, was du brauchst (im scope-Parameter durch Leerzeichen getrennt). Lesen braucht keinen Scope.
| Scope | Erlaubt |
|---|---|
| bookcases.write | Einträge anlegen & bearbeiten, Position verschieben |
| bookcases.delete | Eintrag löschen (Grund erforderlich; ein Snapshot wird archiviert) |
| images.write | Fotos zu einem Eintrag hochladen |
| wishlist.write | Wunschlisten-Einträge hinzufügen |
| watchlist.write | Eintrag für die Nutzer:in beobachten / nicht mehr beobachten |
| ratings.write | Einen Eintrag für die Nutzer:in bewerten (1–5) und ihre Bewertung entfernen |
| home.write | Heimat-Kartenposition der Nutzer:in setzen |
Endpunkt-Referenz
| Methode | Pfad | Auth | Zweck |
|---|---|---|---|
| GET | /api/v1/bookcases | frei | Liste nach Bounding-Box (latMin,latMax,lonMin,lonMax, limit≤1000, offset) |
| GET | /api/v1/bookcases/{id} | frei | Einzelner Eintrag mit Details |
| GET | /api/v1/bookcases/{id}/images | frei | Fotos eines Eintrags auflisten |
| GET | /api/v1/bookcases/{id}/wishlist | frei | Wunschliste eines Eintrags auflisten |
| GET | /api/v1/bookcases/{id}/caretakers | frei | Betreuer:innen eines Eintrags auflisten |
| GET | /api/v1/bookcases/{id}/opening-times | frei | Öffnungszeiten eines Eintrags auflisten |
| GET | /api/v1/bookcases/{id}/rating | frei | Bewertungsübersicht (Anzahl + Durchschnitt) |
| POST | /api/v1/bookcases | bookcases.write | Eintrag anlegen |
| PATCH | /api/v1/bookcases/{id} | bookcases.write | Felder aktualisieren (partiell) |
| POST | /api/v1/bookcases/{id}/position | bookcases.write | Verschieben (latitude/longitude) |
| DELETE | /api/v1/bookcases/{id} | bookcases.delete | Löschen (JSON reason erforderlich) |
| POST | /api/v1/bookcases/{id}/images | images.write | Foto hochladen (multipart) |
| POST | /api/v1/bookcases/{id}/wishlist | wishlist.write | Wunschlisten-Eintrag hinzufügen |
| POST | /api/v1/bookcases/{id}/watch | watchlist.write | Eintrag beobachten |
| DELETE | /api/v1/bookcases/{id}/watch | watchlist.write | Beobachtung beenden |
| POST | /api/v1/profile/home | home.write | Heimatposition der Nutzer:in setzen |
| POST | /api/v1/bookcases/{id}/caretakers | bookcases.write | Betreuer:in zu einem Eintrag hinzufügen |
| PATCH | /api/v1/bookcases/{id}/caretakers/{caretakerId} | bookcases.write | Betreuer:in aktualisieren (partiell) |
| DELETE | /api/v1/bookcases/{id}/caretakers/{caretakerId} | bookcases.write | Betreuer:in entfernen |
| POST | /api/v1/bookcases/{id}/opening-times | bookcases.write | Öffnungszeit hinzufügen |
| PATCH | /api/v1/bookcases/{id}/opening-times/{openingTimeId} | bookcases.write | Öffnungszeit aktualisieren (partiell) |
| DELETE | /api/v1/bookcases/{id}/opening-times/{openingTimeId} | bookcases.write | Öffnungszeit entfernen |
| PUT | /api/v1/bookcases/{id}/rating | ratings.write | Bewertung der Nutzer:in hinzufügen oder aktualisieren (1–5) |
| DELETE | /api/v1/bookcases/{id}/rating | ratings.write | Bewertung der Nutzer:in entfernen |
Das Bearer-Token gehört in den Authorization-Header. Ein Schreibzugriff ohne Token liefert 401, mit falschem Scope 403.
API verwenden
Kartenausschnitt lesen (frei)
curl "https://openbookcase.de/api/v1/bookcases?latMin=52.4&latMax=52.6&lonMin=13.3&lonMax=13.5&limit=200"
Einen Eintrag lesen (frei)
curl https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q0000000000000000
Eintrag anlegen
curl -X POST https://openbookcase.de/api/v1/bookcases \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Gemeinschaftsregal im Park",
"entryType": "bookcase",
"latitude": 52.5200,
"longitude": 13.4050
}'
# → 201 Created, liefert den neuen Eintrag (inkl. id). Titel dürfen keine URLs enthalten.
Felder aktualisieren (partiell)
curl -X PATCH https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q... \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"comment": "Wöchentlich aufgefüllt", "isMobile": false, "accessibilityLevel": 3}'
Eintrag verschieben
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q.../position \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"latitude": 52.5198, "longitude": 13.4042}'
Foto hochladen (multipart)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q.../images \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F imageFile=@regal.jpg \
-F author="Jane Doe" \
-F altText="Vorderansicht des Regals"
# imageFile + author sind Pflicht; altText ist optional. Max. 5 Fotos pro Eintrag.
Eintrag löschen (Grund erforderlich)
curl -X DELETE https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q... \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason": "Bücherschrank wurde vom Eigentümer entfernt"}'
Beobachten · Wunschliste · Heimat
# Eintrag beobachten (bei Änderungen benachrichtigt werden)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../watch \
-H "Authorization: Bearer $ACCESS_TOKEN"
# Wunschlisten-Eintrag hinzufügen (title Pflicht; author/isbn/misc optional)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../wishlist \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"title": "Die linke Hand der Dunkelheit", "author": "Ursula K. Le Guin"}'
# Heimat-Kartenposition der Nutzer:in setzen
curl -X POST https://openbookcase.de/api/v1/profile/home \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"latitude": 52.52, "longitude": 13.405, "zoom": 14}'
Betreuer:innen, Öffnungszeiten & Bewertungen
Betreuer:innen und Öffnungszeiten gehören zum Eintrag, sie nutzen daher bookcases.write. Eine Bewertung gehört zur Nutzer:in, sie nutzt daher ratings.write.
# Betreuer:in hinzufügen (Name und/oder Kontakt erforderlich; Adresse optional)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../caretakers \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Local library", "contact": "hello@example.org",
"address": {"street": "Main St", "houseNumber": "5", "city": "Berlin"}}'
# → 201 Created, liefert die Betreuer:in (inkl. id). PATCH .../caretakers/{id} bearbeitet sie,
# DELETE .../caretakers/{id} löst sie (und entfernt sie, wenn kein Eintrag sie mehr nutzt).
# Öffnungszeit hinzufügen (Freitext text ODER das 24/7-Flag — eines ist erforderlich)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../opening-times \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"openTime": "Mo-Fr 08:00-20:00"}' # oder: {"twentyFourSeven": true}
# PATCH/DELETE .../opening-times/{id} bearbeiten oder entfernen sie.
# Eintrag für die Nutzer:in bewerten (1–5; legt ihre einzige Bewertung an oder aktualisiert sie)
curl -X PUT https://openbookcase.de/api/v1/bookcases/01JZ.../rating \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"value": 5}'
# → liefert {userValue, count, average, rounded}. DELETE .../rating entfernt ihre Bewertung.
Limits & Fehler
- Lesen: 600 Anfragen / Minute, pro IP.
- Schreiben: 60 Anfragen / 10 Minuten, pro Access-Token.
Bei Überschreitung kommt 429 Too Many Requests mit Retry-After-Header (Sekunden) und
X-RateLimit-Limit. Andere Fehler sind JSON mit einer error-Meldung:
400 ungültige Anfrage, 401 fehlendes/ungültiges Token, 403 falscher Scope,
404 nicht gefunden, 422 Validierung fehlgeschlagen (mit violations-Liste).
Datenlizenz & Namensnennung
- Alle Daten auf dieser Seite stehen unter der Open Database License (ODbL).
- Wenn du diese Daten in einem anderen Projekt verwendest, muss auch dieses Projekt unter der ODbL veröffentlicht werden und einen Link zum Lizenztext enthalten.
- OpenBookCase enthält aus OpenStreetMap importierte Daten. Jedes Projekt, das diese Daten nutzt, muss daher OpenStreetMap und seine Mitwirkenden nennen — ein Link zur OpenStreetMap-Urheberrechtsseite ist verpflichtend.
- Diese Daten dürfen nicht zurück nach OpenStreetMap importiert werden. Einträge werden mitunter aus dem Gedächtnis statt an exakten, geprüften Koordinaten erfasst, wodurch sie für OpenStreetMap unbrauchbar sind.