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ź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T00:01:20.579837Z</responseDate>
<request verb="Identify">https://bibliotekanauki.pl/api/oai/articles</request>
<Identify>
    <repositoryName>Biblioteka Nauki - repozytorium artykułów</repositoryName>
    <baseURL>https://bibliotekanauki.pl/api/oai/articles</baseURL>
    <protocolVersion>2.0</protocolVersion>
    <adminEmail>lp.ik1733335608uanak1733335608etoil1733335608bib@n1733335608imda1733335608</adminEmail>
    <earliestDatestamp>1990-02-01T12:00:00Z</earliestDatestamp>
    <deletedRecord>persistent</deletedRecord>
    <granularity>YYYY-MM-DD</granularity>
    <description>
        <oai-identifier xmlns="http://www.openarchives.org/OAI/2.0/oai-identifier"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai-identifier http://www.openarchives.org/OAI/2.0/oai-identifier.xsd">
            <scheme>oai</scheme>
            <repositoryIdentifier>bibliotekanauki.pl</repositoryIdentifier>
            <delimiter>:</delimiter>
            <sampleIdentifier>oai:bibliotekanauki.pl:234</sampleIdentifier>
        </oai-identifier>
    </description>
    <description>
        <friends xmlns="http://www.openarchives.org/OAI/2.0/friends/"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/friends/ http://www.openarchives.org/OAI/2.0/friends.xsd">
            <baseURL>https://bibliotekanauki.pl/api/oai/books</baseURL>
            <baseURL>https://bibliotekanauki.pl/api/oai/chapters</baseURL>
        </friends>
    </description>
</Identify>
</OAI-PMH>

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ź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T00:01:20.579837Z</responseDate>
<request verb="ListMetadataFormats">https://bibliotekanauki.pl/api/oai/articles</request>
<ListMetadataFormats>
    <metadataFormat>
        <metadataPrefix>oai_openaire</metadataPrefix>
        <schema>https://www.openaire.eu/schema/repo-lit/4.0/openaire.xsd</schema>
        <metadataNamespace>http://namespace.openaire.eu/schema/oaire/</metadataNamespace>
    </metadataFormat>
    <metadataFormat>
        <metadataPrefix>jats</metadataPrefix>
        <schema>https://jats.nlm.nih.gov/archiving/1.2/xsd/JATS-archivearticle1.xsd</schema>
        <metadataNamespace>http://jats.nlm.nih.gov</metadataNamespace>
    </metadataFormat>
    <metadataFormat>
        <metadataPrefix>bwmeta</metadataPrefix>
        <schema>http://yadda.icm.edu.pl/bwmeta-2.1.0.xsd</schema>
        <metadataNamespace>http://yadda.icm.edu.pl</metadataNamespace>
    </metadataFormat>
</ListMetadataFormats>
</OAI-PMH>

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ź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T00:01:20.579837Z</responseDate>
<request verb="ListSets">https://bibliotekanauki.pl/api/oai/articles</request>
<ListSets>
    <set>
        <setSpec>1</setSpec>
        <setName>Prace Instytutu Badawczego Leśnictwa</setName>
    </set>
    <set>
        <setSpec>2</setSpec>
        <setName>Innowacyjne Mleczarstwo</setName>
    </set>
    <set>
        <setSpec>3</setSpec>
        <setName>Diagnostyka Laboratoryjna</setName>
    </set>

    <!-- Pozostałe rekordy... -->

</ListSets>
</OAI-PMH>
  • URL: https://bibliotekanauki.pl/api/oai/books?verb=ListSets

  • Odpowiedź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T00:01:20.579837Z</responseDate>
<request verb="ListSets">https://bibliotekanauki.pl/api/oai/books</request>
<error code="noSetHierarchy">The repository does not support sets.</error>
</OAI-PMH>

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ź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T00:01:20.579837Z</responseDate>
<request metadataPrefix="jats" verb="ListRecords">https://bibliotekanauki.pl/api/oai/articles</request>
<ListRecords>
    <record>
        <header>
            <identifier>oai:bibliotekanauki.pl:105</identifier>
            <datestamp>2020-12-09T23:17:11.424Z</datestamp>
        </header>
        <metadata>
             <!-- Metadane w wybranym formacie... -->
        </metadata>
    </record>
    <record>
        <header status="deleted">
            <identifier>oai:bibliotekanauki.pl:107</identifier>
            <datestamp>2020-12-09T23:17:12.235Z</datestamp>
        </header>
    </record>

    <!-- Pozostałe rekordy... -->

</ListRecords>
</OAI-PMH>

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ź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T00:01:20.579837Z</responseDate>
<request metadataPrefix="jats" verb="ListIdentifiers">https://bibliotekanauki.pl/api/oai/articles</request>
<ListRecords>
    <record>
        <header>
            <identifier>oai:bibliotekanauki.pl:105</identifier>
            <datestamp>2020-12-09T23:17:11.424Z</datestamp>
        </header>
    </record>
    <record>
        <header status="deleted">
            <identifier>oai:bibliotekanauki.pl:107</identifier>
            <datestamp>2020-12-09T23:17:12.235Z</datestamp>
        </header>
    </record>

    <!-- Pozostałe rekordy... -->

</ListRecords>
</OAI-PMH>

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ź: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-31T22:40:01.254200Z</responseDate>
<request identifier="oai:bibliotekanauki.pl:202060" metadataPrefix="jats" verb="GetRecord">
    https://bibliotekanauki.pl/api/oai/articles
</request>
<GetRecord>
    <record>
        <header>
            <identifier>oai:bibliotekanauki.pl:202060</identifier>
            <datestamp>2021-01-28T18:00:26.736Z</datestamp>
        </header>
        <metadata>
            <article xmlns:xlink="http://www.w3.org/1999/xlink"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://jats.nlm.nih.gov"
                     xsi:schemaLocation="http://jats.nlm.nih.gov https://jats.nlm.nih.gov/archiving/1.2/xsd/JATS-archivearticle1.xsd">
                <front>
                    <journal-meta>
                        <journal-title-group>
                            <journal-title>Bulletin of the Polish Academy of Sciences. Technical Sciences
                            </journal-title>
                        </journal-title-group>
                        <issn pub-type="ppub">0239-7528</issn>
                        <publisher>
                            <publisher-name>Polska Akademia Nauk. Czytelnia Czasopism PAN</publisher-name>
                        </publisher>
                    </journal-meta>
                    <article-meta>
                        <article-categories>
                            <subj-group>
                                <subject>Engineering and technical sciences</subject>
                                <subj-group>
                                    <subject>mechanical engineering</subject>
                                </subj-group>
                            </subj-group>
                        </article-categories>
                        <title-group>
                            <article-title xml:lang="en">Calculations of transport parameters in semiconductor superlattices based on the Greens’ functions method in different Hamiltonian representations</article-title>
                        </title-group>
                        <article-id pub-id-type="doi">10.24425/bpasts.2019.129661</article-id>
                        <contrib-group>
                            <contrib>
                                <name name-style="western">
                                    <surname>Mączka</surname>
                                    <given-names>M.</given-names>
                                </name>
                                <role>author</role>
                                <xref ref-type="aff" rid="aff-202060-0"></xref>
                            </contrib>
                            <contrib>
                                <name name-style="western">
                                    <surname>Hałdaś</surname>
                                    <given-names>G.</given-names>
                                </name>
                                <role>author</role>
                                <xref ref-type="aff" rid="aff-202060-0"></xref>
                            </contrib>
                        </contrib-group>
                        <aff id="aff-202060-0">
                            <institution content-type="orgname">Department of Electronics Fundamentals, Rzeszów University of Technology, W. Pola 2, 35-959 Rzeszów, Poland</institution>
                        </aff>
                        <pub-date>
                            <year>2019</year>
                        </pub-date>
                        <abstract xml:lang="en">
                            <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>
                        </abstract>
                        <volume>67</volume>
                        <issue>3</issue>
                        <issue-id>11320</issue-id>
                        <fpage>631</fpage>
                        <lpage>641</lpage>
                        <kwd-group xml:lang="en">
                            <kwd>semiconductor superlattices</kwd>
                            <kwd>NEGF formalism</kwd>
                            <kwd>Wannier functions</kwd>
                        </kwd-group>
                        <kwd-group xml:lang="pl">
                            <kwd>nadprzewodnik</kwd>
                            <kwd>półprzewodnik</kwd>
                            <kwd>Formalizm</kwd>
                            <kwd>funkcja Wanniera</kwd>
                        </kwd-group>
                        <self-uri xlink:href="https://3pn.icm.edu.pl/api/full-texts/2020/12/10/086565f1-13e0-40cb-8108-9eb9d85e5d7f.pdf" content-type="application/pdf"></self-uri>
                    </article-meta>
                </front>
            </article>
        </metadata>
    </record>
</GetRecord>
</OAI-PMH>

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: 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T22:05:03.984324Z</responseDate>
<request metadataPrefix="jats" verb="ListRecords">http://bibliotekanauki.pl/api/oai/articles</request>
<ListRecords>
    <record><!-- dane rekordu --></record>
    <record><!-- dane rekordu --></record>
    <record><!-- dane rekordu --></record>
    <!-- ... -->
    <resumptionToken expirationDate="2021-01-01T23:05:03.978Z">
        eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJtZXRhZGF0YVByZWZpeCI6ImphdHMiLCJleHAiOjE2MTIxMzQzMDMsImlhdCI6MTYxMjEzMDcwMywic3RhcnRpbmdJZCI6MTY2Mn0.
    </resumptionToken>
</ListRecords>
</OAI-PMH>
  • 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. 
    <?xml version="1.0" ?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2021-01-01T22:05:08.435765Z</responseDate>
<request metadataPrefix="jats" verb="ListRecords">http://bibliotekanauki.pl/api/oai/articles</request>
<ListRecords>
    <record><!-- dane rekordu --></record>
    <record><!-- dane rekordu --></record>
    <resumptionToken></resumptionToken>
</ListRecords>
</OAI-PMH>

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