API OAI-PMH
Introduction
The platform provides three data repositories compliant with the OAI-PMH specification, one for each type of publication:
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
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
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
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
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.
Additional resources
