BreedersDB

API Einführung

Inhalt

Was ist die BreedersDB API?

BreedersDB bietet eine GraphQL-API, mit der du programmatisch auf deine Daten zugreifen kannst. Dies ist besonders nützlich für:

  • Automatisierte Datenauswertungen (z.B. mit R, Python, oder anderen Analyse-Tools)
  • Integration mit anderen Systemen
  • Massenoperationen auf Daten
  • Erstellung von benutzerdefinierten Berichten und Visualisierungen

Authentifizierung

Um die API zu nutzen, benötigst du ein Persönliches Zugangs-Token (Personal Access Token). Dieses Token identifiziert dich gegenüber der API und gewährt dir Zugriff auf deine Daten.

Weitere Informationen zur Erstellung und Verwaltung von Tokens findest du unter Persönliche Zugangs-Token.

GraphQL-Endpoint

Der GraphQL-Endpoint für deine Instanz ist:

https://{deine-instanz}.breedersdb.com/api/hasura/v1/graphql

Ersetze {deine-instanz} mit dem Namen deiner BreedersDB-Instanz.

Erste Schritte

  1. Token erstellen: Erstelle ein Persönliches Zugangs-Token in BreedersDB (Anleitung)
  2. Explorer testen: Nutze den GraphQL Explorer, um die API interaktiv zu erkunden
  3. Beispiele anschauen: Sieh dir die Beispiel-Abfragen an, um zu verstehen, wie Abfragen strukturiert sind
  4. In Programmen nutzen: Verwende die API in deinen Programmen, z.B. mit R (Anleitung)

Attributierungen abrufen

Attributierungen liest du am besten über den cached_attributions-Endpunkt ab. Da sind alle erfassten Attributierungen (Bonituren, Behandlungen, Beobachtungen, etc.) in einer optimierten, flachen Struktur enthalten. Weitere Informationen und Beispiele findest du in den Beispiel-Abfragen.

Datentypen

Attributierungen werden je nach Datentyp in verschiedenen Feldern ausgegeben:

DatentypFeldnameBeschreibung
INTEGERinteger_valueGanzzahl
RATINGinteger_valueBewertung
FLOATfloat_valueDezimalzahl
TEXTtext_valueText
PHOTOtext_valueFotos
DATEdate_valueDatum
BOOLEANboolean_valueBoolscher Wert (Wahr/Falsch)

Über das Feld data_type erfährst du, welchen Datentyp die jeweilige Attributierung hat.

Fotos in Attributierungen

Bei Fotos wird jeweils der Dateiname im entsprechenden Wert-Feld (text_value resp. photo_note) gespeichert. Um das Foto selbst abzurufen, kannst du die dafür notwendige URL wie folgt zusammensetzen:

  • Foto-Attributierung: https://{deine-instanz}.breedersdb.com/api/assets/images/photo.jpg?file={text_value}
  • Foto-Bemerkung: https://{deine-instanz}.breedersdb.com/api/assets/images/photo.jpg?file={photo_note}

Beispiel: Wenn photo_note den Wert abc123.jpg hat und deine Instanz beta heisst, ist die URL:

https://beta.breedersdb.com/api/assets/images/photo.jpg?file=abc123.jpg

Attributierungen an Pflanzen, Gruppen, Cultivaren und Lose

  • Attributierungen an Losen sind unabhängig.
  • Attributierungen an Pflanzen, Gruppen und Cultivaren werden vererbt:
    • Bei Attributierungen an einer Pflanze erscheinen auch die Gruppe (combined_plant_group_id) und das zugehörige Cultivar (combined_cultivar_id).
    • Bei Attributierungen an einer Gruppe erscheint auch das zugehörige Cultivar (combined_cultivar_id).
    • Attributierungen an einem Cultivar erscheinen nur für dieses Cultivar.
Attributiertplant_idplant_group_idcultivar_idlot_idcombined_plant_group_idcombined_cultivar_id
Pflanze✅nullnullnull✅✅
Gruppenull✅nullnull✅✅
Cultivarnullnull✅nullnull✅
Losnullnullnull✅nullnull

Pagination

Die API ist ziemlich leistungsstark und jede Instanz ist komplett unabhängig. Daher haben wir uns entschlossen, keine harten Limits für Abfragen zu setzen. Wir empfehlen jedoch, Pagination zu verwenden, um die Datenmengen pro Anfrage zu begrenzen. Bei verschachtelten Queries mit vielen Verknüpfungen kann es sinnvoll sein, auch die Anzahl der verschachtelten Einträge zu begrenzen.

Nutze die Argumente limit, offset und order_by, um Pagination zu implementieren. Zum Beispiel:

query PlantsQuery {
  plants(limit: 1000, offset: 5000, order_by: [{ id: asc }]) {
    id
    label_id
    plant_group_name
    cached_attributions(limit: 100, order_by: [{ id: asc }]) {
      id
      attribute_id
      attribute_name
      date_attributed
      data_type
      boolean_value
      date_value
      float_value
      integer_value
      text_value
      photo_note
      text_note
      author
      created
    }
  }
}
  • limit gibt die maximale Anzahl Einträge pro Seite an.
  • offset gibt an, wie viele Einträge übersprungen werden sollen (z.B. für die nächste Seite).
  • order_by gibt an, nach welchem Feld die Einträge sortiert werden sollen.

In diesem Beispiel werden die Pflanzen 5001 bis 6000 abgerufen, jeweils mit 100 Attributierungen pro Pflanze.

GraphQL Dialekt

BreedersDB nutzt den GraphQL Dialekt von Hasura. Details dazu findest du hier:

Weitere Informationen