API OAI-PMH

Introduction

The platform provides three data repositories compliant with the OAI-PMH specification, one for each type of publication:

Articles repository: https://bibliotekanauki.pl/api/oai/articles
Books repository: https://bibliotekanauki.pl/api/oai/books
Repository of chapters of collective works: https://bibliotekanauki.pl/api/oai/chapters

These repositories respond to HTTP requests like GET and POST and return responses like text/xml.
Each request to the repository must contain the parameter verb, which determines the type of response.

`Identify`

The request with the parameter verb with value Identify lets you get basic information about the repository, such as its name, how deleted records are handled, date granulation, ID format, and more. Such requests do not require any additional parameters.

Example

URL: https://bibliotekanauki.pl/api/oai/articles?verb=Identify

Response:

<?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.ik1713569244uanak1713569244etoil1713569244bib@n1713569244imda1713569244</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`

The request with the parameter verb with value ListMetadataFormats provides the information about the supported metadata formats. The articles repository provides records in the following formats:

DublinCore compliant with the requirements of the OpenAire project
JATS
BWMETA

In the books repository and in chapters the JATS (Journal Article Tag Suite) format has been replaced with BITS (Book Interchange Tag Set) format. The requests ListMetadataFormats do not require any additional parameters.

Example

URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListMetadataFormats

Response:

<?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`

The request with the parameter verb with value ListSets allows you to get information about the hierarchy of collections in the specified repository. Currently the collections are supported only in the articles repository. The request ListSets in this repository responds with a flat hierarchy of collection, each set corresponding with one journal. Other repositories do not support sets – the functionality of the sets is described as optional in the OAI-PMH specification – and current implementation responds with the appropriate error code (noSetHierarchy). This situation may change in the future.

Example

URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListSets

Response:

<?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>

    <!-- Remaining records... -->

</ListSets>
</OAI-PMH>

URL: https://bibliotekanauki.pl/api/oai/books?verb=ListSets

Response:

<?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`

The request with the parameter verb with value ListRecords downloads the record list with their full metadata in the format indicated with the parameter metadataPrefix. The deleted records are listed in the response only in the form of heading, without the metadata. The parameter metadataPrefix is required and must take one of the values listed in request response tags “ ListMetadataFormats.

Example

URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats

Response:

<?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>
             <!-- Metadata in selected format... -->
        </metadata>
    </record>
    <record>
        <header status="deleted">
            <identifier>oai:bibliotekanauki.pl:107</identifier>
            <datestamp>2020-12-09T23:17:12.235Z</datestamp>
        </header>
    </record>

    <!-- Remaining records... -->

</ListRecords>
</OAI-PMH>

`ListIdentifiers`

The request with the parameter verb with value ListIdentifiers works like ListRecords, but downloads only headers of the records, without the metadata. The parameter metadataPrefix is required and must take one of the values listed in the indication response to request tags “ ListMetadataFormats.

Example

URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListIdentifiers&metadataPrefix=jats

Response:

<?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>

    <!-- Remaining records... -->

</ListRecords>
</OAI-PMH>

`GetRecord`

The request with parameter verb with value GetRecord returns information about the record with specific ID. The following parameters are required:

metadataPrefix – format of the metadata; must take one of the values listed in the indicators response to request tags “
ListMetadataFormat,
identifier – record ID

Example

URL: https://bibliotekanauki.pl/api/oai/articles?verb=GetRecord&metadataPrefix=jats&identifier=oai:bibliotekanauki.pl:202060

Response:

<?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>

Paging results (resumption token)

In the situation when the number of records that meet request conditions ListRecords, ListIdentifiers or ListSets is higher than the maximum number of records supported in one response, this response will contain the resumption token, which has to be used for the next request. The result of this request will be another part of data that meets the conditions. This step has to be taken until the response will not contain the resumption token.

Parameter resumptionToken is the exclusive type, which means that it has to appear in the request independently. Using the other parameters along with resumptionToken is forbidden. This limitation does not apply to the parameter verb, which must be a part of every request sent to API.

Example

We make the first request ListRecords
- URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats

We receive the response with part of the records that meet the request conditions and with the value 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><!-- record data --></record>
    <record><!-- record data --></record>
    <record><!-- record data --></record>
    <!-- ... -->
    <resumptionToken expirationDate="2021-01-01T23:05:03.978Z">
        eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJtZXRhZGF0YVByZWZpeCI6ImphdHMiLCJleHAiOjE2MTIxMzQzMDMsImlhdCI6MTYxMjEzMDcwMywic3RhcnRpbmdJZCI6MTY2Mn0.
    </resumptionToken>
</ListRecords>
</OAI-PMH>

We make another request ListRecords, this time adding the parameter resumptionToken.
- URL: https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&resumptionToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJtZXRhZGF0YVByZWZpeCI6ImphdHMiLCJleHAiOjE2MTIxMzQzMDMsImlhdCI6MTYxMjEzMDcwMywic3RhcnRpbmdJZCI6MTY2Mn0.

We receive another part of the data and without the token, which means there is no more data that meet the request conditions.

<?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><!-- record data --></record>
    <record><!-- record data --></record>
    <resumptionToken></resumptionToken>
</ListRecords>
</OAI-PMH>

Limit the collection of downloaded data (selective harvesting)

The repositories allow to limit the set of data downloaded with the requests ListRecords and ListIdentifiers to data made, modified or deleted in the certain period of time. The parameters from and untilare used for this. These parameters take values in the format defined in the request response tag “ Identify.

Both limitations (inclusive), therefore:

Value from needs to be interpreted greater than or equal to,
Value until needs to be interpreted less than or equal to.

The articles repository can as well limit the set of data to articles from a certain journal with the parameter set (see chapter ListSets).

Example

The headings of the made, modified or deleted records from 1st of January 2019:
- https://bibliotekanauki.pl/api/oai/articles?verb=ListIdentifiers&metadataPrefix=jats&from=2019-01-01
The headings made, modified or deleted until 2nd of December 2020:
- https://bibliotekanauki.pl/api/oai/articles?verb=ListIdentifiers&metadataPrefix=jats&until=2020-12-02
Records made, modified or deleted from 1st of January 2021 and 1st of February 2021:
- https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats&from=2021-01-01&until=2021-02-01
The headings of the records made, modified or deleted from 1st of January 2019 from the journal with the set of ID 2:
- https://bibliotekanauki.pl/api/oai/articles?verb=ListRecords&metadataPrefix=jats&from=2019-01-01&set=2

Errors

API returns the following errors:

badArgument – The request includes invalid parameters, the requested parameter is missing, the parameter occurs repeatedly, or the value of the parameter is invalid.
badResumptionToken – the value of the parameter resumptionToken is invalid or the token is invalid.
badVerb – the value of the parameter verb is invalid, the parameter occurs repeatedly or does not occur at all.
cannotDisseminateFormat – the indicated metadata format is not supported by the repository.
idDoesNotExist – Record of the indicated ID does not occur in the repository.
noRecordsMatch – no records that meet the conditions defined with parameters from and until.
noSetHierarchy – the repository does not support sets.

API OAI-PMH

Introduction

Identify

Example

ListMetadataFormats

Example

ListSets

Example

ListRecords

Example

ListIdentifiers

Example

GetRecord

Example

Paging results (resumption token)

Example

Limit the collection of downloaded data (selective harvesting)

Example

Errors

Additional resources

`Identify`

`ListMetadataFormats`

`ListSets`

`ListRecords`

`ListIdentifiers`

`GetRecord`