Categories
Bez kategorii

API OAI-PMH Documentation

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

  • URL: https://bibliotekanauki.pl/api/oai/articles?verb=Identify
  • Response:
      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.ik1642588860uanak1642588860etoil1642588860bib@n1642588860imda1642588860
          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

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

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

  • Response:

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

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

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

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

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:
      2021-01-01T22:05:03.984324Z
      http://bibliotekanauki.pl/api/oai/articles
    
          <!-- dane rekordu -->
          <!-- dane rekordu -->
          <!-- dane rekordu -->
          <!-- ... -->
    
              eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJtZXRhZGF0YVByZWZpeCI6ImphdHMiLCJleHAiOjE2MTIxMzQzMDMsImlhdCI6MTYxMjEzMDcwMywic3RhcnRpbmdJZCI6MTY2Mn0.
    
    
    
    
  • 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.
      2021-01-01T22:05:08.435765Z
      http://bibliotekanauki.pl/api/oai/articles
    
          <!-- dane rekordu -->
          <!-- dane rekordu -->
    
    
    
    

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