... | ... | @@ -7,44 +7,88 @@ Zur Nutzung der API wird ein persönliches Token benötigt. Dieses muss bei jede |
|
|
|
|
|
Um ein Token zu erhalten, schreiben Sie bitte eine Mail an info@open-access-monitor.de und beschreiben kurz Ihren Use-Case. Wir werden uns dann schnellstmöglich bei Ihnen melden.
|
|
|
|
|
|
# Endpunkte
|
|
|
|
|
|
Die API besitzt mehrere Endpunkte. Zur besseren Übersichtlichkeit bieten wir [Swagger](https://open-access-monitor.de/api/swagger) an. Dort können alle Endpunkte eingesehen werden sowie ausprobiert werden.
|
|
|
|
|
|
| Endpunkt | Beschreibung |
|
|
|
| ------ | ------ |
|
|
|
| `/api` | Gibt grundlegende Informationen über die API zurück. |
|
|
|
| `/api/data` | Gibt die verfügbaren Datenbanken aus. Aktuell nur `public`. |
|
|
|
| `/api/data/{database}` | Gibt die verfügbaren Sammlungen der Datenbank `database` aus. |
|
|
|
|
|
|
# Verfügbare Datenbanken und Sammlungen
|
|
|
Als Datenbank ist aktuell nur `public` verfügbar. Diese enthällt alle öffentlichen Daten des OAM.
|
|
|
Sammlungen enthalten jeweils einen Aspekt des OAM und sind mit Tabellen in SQL-Datenbanken vergleichbar.
|
|
|
|
|
|
| Sammlung | Beschreibung |
|
|
|
| ------ | ------ |
|
|
|
| Publications | Metadaten der Publikationen. Für jedes Quellsystem (siehe `source_data.source`) wird ein seperater Eintrag angelegt, d.h. es können mehrere Einträge pro DOI existieren. |
|
|
|
| PublicationCosts| Metadaten für Publikationskosten. Für jedes Quellsystem (siehe `source_data.source`) wird ein seperater Eintrag angelegt, d.h. es können mehrere Einträge pro DOI existieren. |
|
|
|
| Organisations | Metadaten für alle Einrichtungen, zu denen Daten im OAM enthalten sind. |
|
|
|
| Publishers | Metadaten für alle Verlage, zu denen Daten im OAM enthalten sind. |
|
|
|
| Journals | Metadaten für alle Zeitschriften, zu denen Daten im OAM enthalten sind. |
|
|
|
|
|
|
Zusätzlich gibt es je Sammlung eine weitere mit dem Suffix `_old`, welche die Daten der Vorwoche enthält (in der Regel Aktualisierung jeden Sonntag).
|
|
|
|
|
|
# Schema der Daten
|
|
|
Das Metadaten-Schema ist [hier](https://jugit.fz-juelich.de/synoa/oam-dokumentation/-/wikis/Open%20Access%20Monitor/Datenbankschema) beschrieben.
|
|
|
|
|
|
# Datenabfrage
|
|
|
Zur Datenabfrage wird folgender Endpunkt benötigt:
|
|
|
Zur Datenabfrage wird folgender Endpunkt benötigt: `/data/{database}`
|
|
|
|
|
|
`/data/{database}`
|
|
|
Dem Endpunkt kann mittels dem Parameter `query` eine Abfrage übergeben werden. Als mögliche Abfragen können diverse [MongoDB-Commands](https://www.mongodb.com/docs/manual/reference/command/) verwendet werden. Diese müssen als JSON-Objekt formatiert sein.
|
|
|
|
|
|
Als `database` kann aktuell nur "public" genutzt werden. Die Abfrage wird mittels `query` Parameter übergeben. Dieser nimmt [MongoDB-Commands](https://www.mongodb.com/docs/manual/reference/command/) an.
|
|
|
Folgende Commands werden von der API unterstützt:
|
|
|
* [find](https://www.mongodb.com/docs/manual/reference/command/find/)
|
|
|
* [aggregate](https://www.mongodb.com/docs/manual/reference/command/aggregate/)
|
|
|
* [count](https://www.mongodb.com/docs/manual/reference/command/count/)
|
|
|
* [distinct](https://www.mongodb.com/docs/manual/reference/command/distinct/)
|
|
|
* [getMore](https://www.mongodb.com/docs/manual/reference/command/getMore/)
|
|
|
* [mapReduce](https://www.mongodb.com/docs/manual/reference/command/mapReduce/)
|
|
|
* [listCollections](https://www.mongodb.com/docs/manual/reference/command/listCollections/)
|
|
|
|
|
|
Alle API Antworten sind entsprechend der zugehörigen MongoDB-Antwort formatiert.
|
|
|
|
|
|
Die Entitäten sind [hier](https://jugit.fz-juelich.de/synoa/oam-dokumentation/-/wikis/Open%20Access%20Monitor/Datenbankschema) beschrieben. Mögliche Collections zur Abfrage sind:
|
|
|
* Publications
|
|
|
* PublicationCosts
|
|
|
* Journals
|
|
|
* Publishers
|
|
|
* Organisations
|
|
|
|
|
|
Zusätzlich gibt es je Collection eine weitere mit dem Suffix `_old`, welche die Daten der Vorwoche enthält (Aktualisierung jeden Sonntag). Eine Liste aller Collections lässt sich mit folgendem Endpunkt angezeigt werden, wenn der `query` Parameter ausgelassen wird.
|
|
|
|
|
|
| Command | Funktion |
|
|
|
| ------ | ------ |
|
|
|
| [find](https://www.mongodb.com/docs/manual/reference/command/find/) | Einfache Holen von Datensätzen|
|
|
|
| [aggregate](https://www.mongodb.com/docs/manual/reference/command/aggregate/) | Komplexe Abfragen (Gruppierungen, etc.) |
|
|
|
| [count](https://www.mongodb.com/docs/manual/reference/command/count/) | Zählungen |
|
|
|
| [distinct](https://www.mongodb.com/docs/manual/reference/command/distinct/) | Abfrage einzelner Felder ohne Dublikate|
|
|
|
| [getMore](https://www.mongodb.com/docs/manual/reference/command/getMore/) | Wird benötigt bei großen Datenmengen (siehe unten)|
|
|
|
|
|
|
Alle API Antworten sind entsprechend der MongoDB-Dokumentation formatiert.
|
|
|
|
|
|
# Der `aggregate`-Command
|
|
|
|
|
|
Der [`aggregate`-Command](https://www.mongodb.com/docs/manual/reference/command/aggregate/) kann generell für alle Abfragen eingesetzt werden. `find` und `count` sind nur vereinfachte Versionen hiervon.
|
|
|
Um eine Abfrage an die Datenbank zu stellen müsste dem `query`-Parameter im Minimalfall folgendes übergeben werden:
|
|
|
```
|
|
|
{
|
|
|
aggregate: "<Sammlung>",
|
|
|
pipeline: [ <Stage>, <...> ],
|
|
|
cursor: {},
|
|
|
}
|
|
|
```
|
|
|
Für eine Abfrage mit `aggregate` muss eine Pipeline angebeben werden. Eine Pipeline besteht aus mehreren Stages die in der Reihenfolge ihrer Angabe abgearbeitet werden. So lassen sich beliebig komplexe Abfragen erstellen. Nachfolgend werden die wichtigsten Stages aufgelistet, eine Dokumentation aller Stages ist [hier ](https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/) verfügbar.
|
|
|
|
|
|
| Stage | Beschreibung |
|
|
|
| ------ | ------ |
|
|
|
| `$addFields` | Hinzufügen eigener Felder |
|
|
|
| `$match` | Filterung von Dokumenten |
|
|
|
| `$count` | Zählung von Dokumenten |
|
|
|
| `$group`| Gruppierung von Dokumenten |
|
|
|
| `$limit` | Beschränkung auf `x` Ergebnisse |
|
|
|
| `$skip` | Überspringen der ersten `x` Ergebnisse |
|
|
|
| `$project` | Auswahl bestimmter Felder |
|
|
|
| `$sort` | Sortierung der Dokumente |
|
|
|
| `$unwind` | Ausrollen eines Array-Felds |
|
|
|
|
|
|
|
|
|
OA-Kategorien werden innerhalb der Daten entsprechend der Tabelle im Abschnitt [OA-Kategorien](https://jugit.fz-juelich.de/synoa/oam-dokumentation/-/wikis/Open%20Access%20Monitor/OA%20Kategorien) als Zahl codiert.
|
|
|
# Abfrage großer Ergebnismengen
|
|
|
|
|
|
**Wichtig:** Benutzen Sie nicht `skip` und `limit` um alle Dokumente einer großen Ergebnismenge abzufragen.
|
|
|
|
|
|
Für die Abfrage großer Ergebnismengen bietet die API ein Cursor-System. Das Feld `cursor.id` gibt an, ob es weitere Daten in der Ergebnismenge gibt. Dabei bedeutet ein Wert größer `0` das weitere Daten ausstehen.
|
|
|
Der MongoDB-Command `getMore` kann dann mit Hilfe dieser ID dazu genutzt werden weitere Ergebnisse der Abfrage zu erhalten.
|
|
|
|
|
|
# Beispiele
|
|
|
* Abfrage aller Publikationen aus 2020, welche Gold-Open-Access sind \
|
|
|
[https://open-access-monitor.de/api/Data/`public`?token=`<token>`&query=`{find:"Publications", filter:{year: 2018, oa_color: 7}}`](https://open-access-monitor.de/api/Data/public?token=<token>&query=%7Bfind%3A%22Publications%22%2C%20filter%3A%7Byear%3A%202018%2C%20oa_color%3A%207%7D%7D)
|
|
|
[https://open-access-monitor.de/api/Data/`public`?token=`<token>`&query=`{find:"Publications", filter:{year: 2020, oa_color: 7}}`](https://open-access-monitor.de/api/Data/public?token=<token>&query=%7Bfind%3A%22Publications%22%2C%20filter%3A%7Byear%3A%202020%2C%20oa_color%3A%207%7D%7D)
|
|
|
* Zeitschriften, welche in der DFG-Förderliste enthalten sind \
|
|
|
[https://open-access-monitor.de/api/Data/`public`?token=`<token>`&query=`{find:"Journals", filter:{flags: "DFG-Anträge"}}`](https://open-access-monitor.de/api/Data/public?token=<token>&query=%7Bfind%3A%22Journals%22%2C%20filter%3A%7Bflags%3A%20%22DFG-Antr%C3%A4ge%22%7D%7D)
|
|
|
* Anzahl Publikationen pro OA-Kategorie \
|
|
|
[https://open-access-monitor.de/api/Data/`public`?token=`<token>`&query=`{aggregate:"Publications", cursor:{}, pipeline:[{$group:{_id:"$oa_color", sum:{$sum: 1}}}]}`](https://open-access-monitor.de/api/Data/public?token=<token>&query=%7Baggregate%3A%22Publications%22%2C%20cursor%3A%7B%7D%2C%20pipeline%3A%5B%7B%24group%3A%7B_id%3A%22%24oa_color%22%2C%20sum%3A%7B%24sum%3A%201%7D%7D%7D%5D%7D)
|
|
|
|
|
|
# Swagger
|
|
|
|
|
|
Zur besseren Übersichtlichkeit bieten wir [Swagger](https://open-access-monitor.de/api/swagger) an. Dort können alle Endpunkte eingesehen werden sowie ausprobiert werden.
|
|
|
|