Kategorie
Bez kategorii

Dokumentacja API OAI-PMH

API OAI-PMH

Wstęp

Platforma udostępnia trzy repozytoria danych zgodne ze specyfikacją OAI-PMH, po jednym dla każdego typu publikacji:

  • Repozytorium artykułów: https://bibliotekanauki.pl/api/oai/articles
  • Repozytorium książek: https://bibliotekanauki.pl/api/oai/books
  • Repozytorium rozdziałów prac zbiorowych: https://bibliotekanauki.pl/api/oai/chapters

Repozytoria te odpowiadają na żądania HTTP typu GET oraz POST i zwracają odpowiedzi typu text/xml.
Każde żądanie do repozytorium musi zawierać parametr verb, który decyduje o rodzaju odpowiedzi.

Identify

Żądanie z parametrem verb o wartości Identify pozwala uzyskać podstawowe informacje o repozytorium, takie jak jego nazwa, sposób obsługiwania rekordów usuniętych, granulacja dat, format identyfikatorów i inne. Takie żądania nie wymagają żadnych dodatkowych parameterów.

Przykład

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=Identify
  • Odpowiedź:
      2021-01-01T00:01:20.579837Z
      https://bibliotekanauki.pl/api/oai/articles
    
          Biblioteka Nauki - repozytorium artykułów
          https://bibliotekanauki.pl/api/oai/articles
          2.0
          lp.ik1634924106uanak1634924106etoil1634924106bib@n1634924106imda1634924106
          1990-02-01T12:00:00Z
          persistent
          YYYY-MM-DD
    
    
                  oai
                  bibliotekanauki.pl
                  :
                  oai:bibliotekanauki.pl:234
    
    
    
    
                  https://bibliotekanauki.pl/api/oai/books
                  https://bibliotekanauki.pl/api/oai/chapters
    
    
    
    
    

ListMetadataFormats

Żądanie z parametrem verb o wartości ListMetadataFormats pozwala uzyskać infromacje o obsługiwanych formatach metadanych. Repozytorium artykułów udostępnia rekordy w następujących formatach:

  • DublinCore zgodny z wymaganiami projektu OpenAire
  • JATS
  • BWMETA

W repozytoriach książek i rozdziałów format JATS (Journal Article Tag Suite) został zastąpiony formatem BITS (Book Interchange Tag Set). Żądania ListMetadataFormats nie wymagają żadnych dodatkowych parametrów.

Przykład

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListMetadataFormats
  • Odpowiedź:
      2021-01-01T00:01:20.579837Z
      https://bibliotekanauki.pl/api/oai/articles
    
    
              oai_openaire
              https://www.openaire.eu/schema/repo-lit/4.0/openaire.xsd
              http://namespace.openaire.eu/schema/oaire/
    
    
              jats
              https://jats.nlm.nih.gov/archiving/1.2/xsd/JATS-archivearticle1.xsd
              http://jats.nlm.nih.gov
    
    
              bwmeta
              http://yadda.icm.edu.pl/bwmeta-2.1.0.xsd
              http://yadda.icm.edu.pl
    
    
    
    

ListSets

Żądanie z parametrem verb o wartości ListSets pozwala uzyskać informacje o hierarchii zbiorów we wskazanym repozytorium. Obecnie zbiory obsługiwane są wyłącznie w repozytorium artykułów. Żądanie ListSets w tym repozytorium zwraca płaską hierarchię zbiorów, każdy zbiór odpowiada jednemu czasopismu. Pozostałe repozytoria nie obsługują zbiorów – funkcjonalność zbiorów jest w specyfikacji OAI-PMH opisana jako opcjonalna – i obecna implementacja odpowiada stosownym kodem błędu (noSetHierarchy). Sytuacja ta może ulec zmianie w przyszłości.

Przykład

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListSets
  • Odpowiedź:
      2021-01-01T00:01:20.579837Z
      https://bibliotekanauki.pl/api/oai/articles
    
    
              1
              Prace Instytutu Badawczego Leśnictwa
    
    
              2
              Innowacyjne Mleczarstwo
    
    
              3
              Diagnostyka Laboratoryjna
    
    
          <!-- Pozostałe rekordy... -->
    
    
    
    
  • URL: https://bibliotekanauki.pl/api/oai/books?verb=ListSets

  • Odpowiedź:

      2021-01-01T00:01:20.579837Z
      https://bibliotekanauki.pl/api/oai/books
      The repository does not support sets.
    
    

ListRecords

Żądanie z parametrem verb o wartości ListRecords pobiera listę rekordów wraz z ich pełnymi metadanymi w formacie wskazanym przy użyciu parametru metadataPrefix. Rekody usunięte są wymienione w odpowiedzi jedynie w postaci nagłówka, bez metadanych. Parametr metadataPrefix jest wymagany i musi przyjmować jedną z wartości wymienionych w znacznikach „ odpowiedzi na żądanie ListMetadataFormats.

Przykład

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats
  • Odpowiedź:
      2021-01-01T00:01:20.579837Z
      https://bibliotekanauki.pl/api/oai/articles
    
    
              <header>
                  oai:bibliotekanauki.pl:105
                  2020-12-09T23:17:11.424Z
              </header>
    
                   <!-- Metadane w wybranym formacie... -->
    
    
    
              <header>
                  oai:bibliotekanauki.pl:107
                  2020-12-09T23:17:12.235Z
              </header>
    
    
          <!-- Pozostałe rekordy... -->
    
    
    
    

ListIdentifiers

Żądanie z parametrem verb o wartości ListIdentifiers działa tak jak ListRecords, ale pobiera jedynie nagłówki rekordów, bez metadanych. Parametr metadataPrefix jest wymagany i musi przyjmować jedną z wartości wymienionych w znacznikach „ odpowiedzi na żądanie ListMetadataFormats.

Przykład

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListIdentifiers&metadataPrefix=jats
  • Odpowiedź:
      2021-01-01T00:01:20.579837Z
      https://bibliotekanauki.pl/api/oai/articles
    
    
              <header>
                  oai:bibliotekanauki.pl:105
                  2020-12-09T23:17:11.424Z
              </header>
    
    
              <header>
                  oai:bibliotekanauki.pl:107
                  2020-12-09T23:17:12.235Z
              </header>
    
    
          <!-- Pozostałe rekordy... -->
    
    
    
    

GetRecord

Żądanie z parametrem verb o wartości GetRecord zwraca informacje o rekordzie o wskazanym identyfikatorze. Następujące parametry są wymagane:

  • metadataPrefix – format metadanych; musi przyjmować jedną z wartości wymienionych w znacznikach „
    odpowiedzi na żądanie ListMetadataFormat,
  • identifier – identyfikator rekodu

Przykład

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=GetRecord&metadataPrefix=jats&identifier=oai:bibliotekanauki.pl:202060
  • Odpowiedź:
      2021-01-31T22:40:01.254200Z
    
          https://bibliotekanauki.pl/api/oai/articles
    
    
    
              <header>
                  oai:bibliotekanauki.pl:202060
                  2021-01-28T18:00:26.736Z
              </header>
    
                  <article>
    
    
    
                                  Bulletin of the Polish Academy of Sciences. Technical Sciences
    
    
                              0239-7528
    
                                  Polska Akademia Nauk. Czytelnia Czasopism PAN
    
    
    
    
    
                                      Engineering and technical sciences
    
                                          mechanical engineering
    
    
    
    
                                  Calculations of transport parameters in semiconductor superlattices based on the Greens’ functions method in different Hamiltonian representations
    
                              10.24425/bpasts.2019.129661
    
    
    
                                          Mączka
                                          M.
    
                                      author
    
    
    
    
                                          Hałdaś
                                          G.
    
                                      author
    
    
    
    
                                  Department of Electronics Fundamentals, Rzeszów University of Technology, W. Pola 2, 35-959 Rzeszów, Poland
    
    
                                  2019
    
    
                                  <p>Two methods for calculating transport parameters in semiconductor superlattices by applying Green’s functions are compared in the paper. For one of the methods, the Wannier functions method, where computations in the complex space and Wannier functions base are required, the Hamiltonian matrix is small in size and its elements depend solely on the energy. For the real space method, as it operates in the floating point domain and uses the Hamiltonian containing the elements dependent both on energy and position, the Hamiltonian matrix is larger in size. The size makes the method computationally challenging. To find the consequences of choosing one of the methods, a?direct comparison between the computations, obtained for both methods with the same input parameters, was undertaken. The differences between the results are shown and explained. Selected simulations allowed us to discuss advantages and disadvantages of both methods. The calculations include transport parameters such as the density of states and the occupation functions, with regard to scattering processes where the self-consistent Born approximation was used, as well as the spatial distribution of electron concentration for two superlattices structures. The numerical results are obtained within the non-equilibrium Green’s functions formalism by solving the Dyson and the Keldysh equations.</p>
    
                              67
                              3
                              11320
                              631
                              641
    
                                  semiconductor superlattices
                                  NEGF formalism
                                  Wannier functions
    
    
                                  nadprzewodnik
                                  półprzewodnik
                                  Formalizm
                                  funkcja Wanniera
    
    
    
    
                  </article>
    
    
    
    
    

Stronicowanie wyników (resumption token)

W sytuacji gdy liczba rekordów spełniających warunki żądania ListRecords, ListIdentifiers lub ListSets jest wyższa niż maksymalna obsługiwana liczba rekordów zwracanych w jednej odpowiedzi, odpowiedź ta będzie zawierać tzw. resumption token, którego należy użyć do wykonania kolejnego żądania. Wynikiem tego żądania będzie kolejna porcja danych spełniających warunki. Krok ten należy powtarzać aż do uzyskania odpowiedzi nie zawierającej resumption tokena.

Parametr resumptionToken jest parametrem typu exclusive, co oznacza że musi on występować w żądaniu samodzielnie. Używanie innych parametrów razem z resumptionToken jest niedozwolone. Ograniczenie to nie dotyczy parametru verb, który musi być częścią każdego żądania wysyłanego do API.

Przykład

  • Wykonujemu pierwsze żądanie ListRecords
    • URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats
  • Otrzymujemy odpowiedź z częścią rekordów spełniających warunki żądania oraz z wartością resumptionToken:
      2021-01-01T22:05:03.984324Z
      http://bibliotekanauki.pl/api/oai/articles
    
          <!-- dane rekordu -->
          <!-- dane rekordu -->
          <!-- dane rekordu -->
          <!-- ... -->
    
              eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJtZXRhZGF0YVByZWZpeCI6ImphdHMiLCJleHAiOjE2MTIxMzQzMDMsImlhdCI6MTYxMjEzMDcwMywic3RhcnRpbmdJZCI6MTY2Mn0.
    
    
    
    
  • Wykonujemy kolejne żądanie ListRecords, tym razem dołączamy parametr resumptionToken.
    • URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&resumptionToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJtZXRhZGF0YVByZWZpeCI6ImphdHMiLCJleHAiOjE2MTIxMzQzMDMsImlhdCI6MTYxMjEzMDcwMywic3RhcnRpbmdJZCI6MTY2Mn0.
  • Otrzymujemy odpowiedź z kolejną porcją danych i bez tokena, co oznacza że nie ma więcej danych spełniających warunki żądania.
      2021-01-01T22:05:08.435765Z
      http://bibliotekanauki.pl/api/oai/articles
    
          <!-- dane rekordu -->
          <!-- dane rekordu -->
    
    
    
    

Ograniczanie zbioru pobieranych danych (selective harvesting)

Repozytoria umożliwiają ograniczanie zbioru danych pobieranych żądaniami ListRecords i ListIdentifiers do danych utworzonych, zmodyfikowanych lub usuniętych w danym okresie czasu. Służą do tego parametry from oraz until. Parametry te przyjmują wartości w formacie zdefiniowanym w znaczniku „ odpowiedzi na żądanie Identify.

Oba ograniczenia są włączne (inclusive), a więc:

  • wartość from należy interpretować jako większe lub równe,
  • wartość until należy interpretować jako mniejsze lub równe.

Repozytorim artykułów umożliwia również ograniczenie zbioru danych do artykułów ze wskazanego czasopisma przy użyciu paramertu set (patrz rozdział ListSets).

Przykłady

  • Nagłówki rekordów utworzonych, zmodyfikowanych lub usuniętych od 1 stycznia 2019r:
    • https://bibliotekanauki.pl/api/oai/articles?verb=ListIdentifiers&metadataPrefix=jats&from=2019-01-01
  • Nagłówki rekordów utworzonych, zmodyfikowanych lub usuniętych do 2 grudnia 2020:
    • https://bibliotekanauki.pl/api/oai/articles?verb=ListIdentifiers&metadataPrefix=jats&until=2020-12-02
  • Rekordy utworzone, zmodyfikowane lob usunięte pomiędzy 1 stycznia 2021 i 1 lutego 2021:
    • https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats&from=2021-01-01&until=2021-02-01
  • Nagłówki rekordów utworzonych, zmodyfikowanych lub usuniętych od 1 stycznia 2019r z czasopisma reprezentowanego zbiorem o identyfikatorze 2:
    • https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats&from=2019-01-01&set=2

Błędy

API zwraca następujące błędy:

  • badArgument – Żądanie zawiera nieprawidłowe parametry, brakuje wymaganego parametru, parametr występuje wielokrotnie, lub wartość parametru jest nieprawidłowa.
  • badResumptionToken – Wartość parametru resumptionToken jest nieprawidłowa lub token jest nieważny.
  • badVerb – Wartość parametru verb jest nieprawidłowa, parametr występuje wielokrotnie lub nie występuje wcale.
  • cannotDisseminateFormat – Wskazany format metadanych nie jest obsługiwany przez repozytorium.
  • idDoesNotExist – Rekord o wskazanym identyfikatorze nie występuje w repozytorium.
  • noRecordsMatch – Brak rekordów spełniających warunki zdefiniowane parametrami from i until.
  • noSetHierarchy – Repozytorium nie obsługuje zbiorów.

Zasoby dodatkowe