Dabar REST API - Podrška za automatiziranu dostavu digitalnih objekata u Dabar

Pristup REST API sučelju
BagIt specifikacija (v1.1.2)
REST API dokumentacija (v1.1.0)

Dabar podržava automatiziranu pohranu digitalnih objekata u repozitorije ustanova putem REST programskog sučelja (Dabar REST API). Ta funkcionalnost namijenjena je vlasnicima repozitorija koji:

• imaju informacijske sustave ili uređaje iz kojih žele prenositi digitalne objekte u repozitorij u Dabru
• žele kopirati digitalne objekte iz svojih repozitorija izvan Dabra u Dabar zbog ispunjavanja zakonskih obaveza ili kreiranja sigurnosne kopije digitalnih objekata
• žele migrirati digitalne objekte iz svojih postojećih repozitorija izvan Dabra u repozitorij uspostavljen u Dabru.

Pristup REST API sučelju

Odgovorna osoba zadužena za upravljanje repozitorijem mora poslati zahtjev na dabar@srce.hr s kratkim obrazloženjem načina na koji ustanova namjerava koristiti REST API sučelje. Nakon potvrđenog zahtjeva slijedite daljnje upute u nastavku.

Urednici repozitorija koji žele omogućiti pristup REST API sučelju moraju označiti polje 'Omogući REST API sučelje' u postavkama repozitorija kojim upravljaju. Pristupni podaci će se nakon toga proslijediti na e-mail adresu odgovorne osobe za uspostavu i održavanje repozitorija.

Za pristup REST API resursima potrebna je autentikacija i autorizacija, a način autentifikacije je Basic access authentication. Obavezno se upisuju i IP adrese s kojih će se pristupati REST API sučelju.

Novi REST API korisnik se kreira u odjeljku NOVI KORISNIK. Pri kreiranju novog korisnika potrebno je upisati korisničko ime u polje "Korisničko ime" i kliknuti "Dodaj korisnika" nakon čega će obavijest zajedno sa korisničkom lozinkom biti poslana Odgovornoj osobi za repozitorij.

Za pristup testnom REST API sučelju obratite se na dabar@srce.hr.

BagIt specifikacija (v1.1.2)

Objekti će se dostavljati u hijerarhijskom formatu za pakiranje datoteka BagIt (http://www.dcc.ac.uk/resources/external/bagit-library). BagIt kontejner je potrebno dostaviti u .zip formatu čiji naziv je proizvoljan, ali je prema specifikaciji (str. 12, 4. Serialization) naziv .zip kontejnera identičan nazivu direktorija koji se u njemu nalazi. Pogledajte primjer za naziv "zavrsni".

Struktura kontejnera (ocjenski radovi)

{Torba}.zip
  [{Torba}]
    [data]
      [rad]
        {Naziv}.pdf
        {Naziv}.xml
      [prilozi]
        {Naziv_0}.{dozvoljeni format priloga}
        {Naziv_0}.xml
        {Naziv_1}.{dozvoljeni format priloga}
        {Naziv_1}.xml
        ...
    bag-info.txt
    bagit.txt
    manifest-sha1.txt
    tagmanifest-sha1.txt

Struktura kontejnera (obrazovni sadržaj, radovi objavljeni u časopisu, poglavlja u knjizi, knjiga, izlaganje na skupu, radovi objavljeni u zborniku, ostale vrste dokumenata)

{Torba}.zip
  [{Torba}]
    [data]
      [rad]
         [datoteke]
           naziv_datoteke_1.extenzija
           naziv_datoteke_2.extenzija
           ...
           ...
           ...
         [metapodaci]
           mods.xml
           naziv_datoteke_1.xml
           naziv_datoteke_2.xml
           ...
           ...
           ...
      [prilozi]
        {Naziv_0}.{dozvoljeni format priloga}
        {Naziv_0}.xml
        {Naziv_1}.{dozvoljeni format priloga}
        {Naziv_1}.xml
        ...
    bag-info.txt
    bagit.txt
    manifest-sha1.txt
    tagmanifest-sha1.txt

Opis strukture (ocjenski radovi)

Simbol '[...]' predstavlja direktorij.

Završni, diplomski i specijalistički radovi te disertacije i znanstveni magistarski radovi se pohranjuju u direktorij [rad]. Jedan BagIt kontejner sadrži sve potrebno za opisivanje samo jednoga rada, a direktorij koji sadrži rad uvijek ima dvije datoteke:

• rad (.pdf)
• pripadajući metapodatkovni opis (.xml)

Datoteke je potrebno imenovati tako da su nazivi identični.

Opis strukture (obrazovni sadržaj, radovi objavljeni u časopisu, poglavlja u knjizi, knjiga, izlaganje na skupu, radovi objavljeni u zborniku)

Simbol '[...]' predstavlja direktorij.

Datoteke obrazovnog sadržaja se pohranjuju u direktorij [rad][datoteke]. Metapodaci obrazovnog sadržaja se pohranjuju u direktorij [rad][metapodaci]. Jedan BagIt kontejner sadrži sve potrebno za opisivanje samo jednoga obrazovnog objekta, a direktorij rad uvijek ima dva poddirektorija:

• [datoteke] - sadrži datoteke obrazovnog sadržaja
• [metapodaci] - sadrži metapodatkovne opise cjelokupnog objekta i svake datoteke posebno

         - mods.xml - metapodaci cijelog objekta

         - naziv_datoteke_1.xml, naziv_datoteke_2.xml ... - metapodatci svake datoteke (prava pristupa, licenca  ....)

Datoteke s metapodatcima pojedinih datoteka unutar [metapodaci] direktorija je potrebno imenovati tako da su nazivi identični nazivma datoteka objekta u [datoteke] direktoriju.

Prilozi su smješteni u direktorij [prilozi], a svaki prilog ima pripadajuću MODS XML datoteku identičnog naziva kao i prilog uz koji je vezana. Pohraniti se mogu samo odabrane vrste priloga (pdf tif tiff png jpg jpeg), ali rad se može pohraniti i bez priloga.

bag-info.txt sadrži informacije o kontejneru. Dodatna polja uz automatski generirana Payload-Oxum, Bagging-Date i Bag-Size su podaci o uredniku, tj. osobi koja se upisuje kao pohranitelj objekta te stanju objekta nakon pohrane:

• UREDNIK_IME: Ime urednika
• UREDNIK_PREZIME: Prezime rednika
• UREDNIK_OIB: OIB
• UREDNIK_ULOGA (opcionalno): Uloga urednika
  • ovaj parametar nije obavezan ukoliko uloga nije unesena automatski se dodaje uloga 'API administrator'
  • dozvoljene uloge su :
    • student
    • djelatnik
    • urednik
    • API administrator
• OBJEKT_AKTIVAN (opcionalno): Stanje objekta nakon pohrane
  • 0 - objekt neće biti aktivan
  • 1 - objekt se postavlja u aktivno stanje

bagit.txt sadrži verziju prema kojoj je kontejner nastao i vrstu znakovnog zapisa (encoding).

manifest-sha1.txt sadrži SHA-1 sažetak svih datoteka smještenih u [data] direktoriju. Temeljem ovih podataka se validira integritet informacija koje su se prenijele. Format zapisa je:

{SHA-1} data/{Direktorij}/{Naziv}.pdf
{SHA-1} data/{Direktorij}/{Naziv}.xml
...

tagmanifest-sha1.txt sadrži podatke u istom formatu kao i manifest-sha1.txt, ali opisuje bag-info.txt, bagit.txt i manifest-sha1.txt datoteke.

Primjeri BagIt kontejnera su izrađeni pomoću Bagger Java aplikacije:

• zavrsni.zip(zip, 781KB)
• disertacija.zip(zip, 786KB)
• obrazovni.zip(zip, 35KB)
• clanci.zip(zip, 39KB)
• ins.zip(zip, 37KB)
• knjige.zip(zip, 37KB)
• puk.zip(zip, 38KB)
• ruz.zip(zip, 39KB)
• ostalo.zip(zip, 37KB)

Dabar validira dostavljene BagIt kontejnere koristeći BagItPHP, ali postoje i drugi primjeri biblioteka koje pružaju mogućnost kreiranja, otvaranja i validacije BagIt kontejnera.

Primjeri metapodatkovnog opisa objekata (MODS)

Primjeri XML datoteka za objekt koji se pohranjuje može se pronaći u nastavku. Molimo obratite pozornost na redoslijed i točno navođenje imenskog prostora prema primjerima:

• MODS_zavrsni.xml(xml, 9 KB)
• MODS_disertacije.xml(xml, 14 KB)
• MODS_prilozi.xml(xml, 4 KB)
• MODS_obrazovni.xml(xml, 6 KB)
• MODS_clanci.xml(xml, 9 KB)
• MODS_ins.xml(xml, 7 KB)
• MODS_knjige.xml(xml, 8 KB)
• MODS_puk.xml(xml, 8 KB)
• MODS_ruz.xml(xml, 9 KB)
• MODS_ostalo.xml(xml, 6 KB)

Popis licencija za korištenje u XML datotekama s detaljnim opisom o načinu korištenja:

• licencije.txt

Pomoćne oznake pri opisu XML datoteka:

• []: Definiran set podataka iz kojeg se odabire vrijednost.
• {}: Slobodan unos podataka.
• /r <broj ponavljanja>: Ponovljivo polje koje može imati ograničen ili neograničen broj ponavljanja.
• /N: Obavezno polje. Sva polja niže u stablu su također obavezna ako nije drugačije naznačeno.
• ~: Komentari uz polja nastoje korisniku olakšati snalaženje.

Preporuka je koristiti propisanu specifikaciju za bolje razumijevanje opisane XML datoteke. Specifikacija metapodataka koji se dostavljaju definirana je na stranici s popisom podržanih objekata.

REST API dokumentacija (v1.1.0)

REST API server: https://{URL repozitorija}/api

Autentifikacija korisnika za pristup resursima se vrši Basic access authentication metodom. Primjer dodanog polja u zaglavlje (header):

Authorization: Basic YWxlbjpsZXRtZWlu

Accept: application/json

200 OK

{
  "pid": "fer:1234",
  "naslov": "Naslov",
  "datum_pohrane": "2015-10-12T14:38:30.862Z",
  "datum_zadnje_izmjene": "2016-04-26T06:31:47.609Z",
  "povezani_objekti": {
    "prilozi": [
      {
        "pid": "fer:2345"
      },
      {
        "pid": "fer:3456"
      }
    ]
  }
}

200 OK - uspješno dohvaćeni rezultati

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

404 Not Found - rad ne postoji u repozitoriju

Accept: application/json
Content-Type: multipart/form-data

Parametri
bagit: test.zip

202 Accepted

HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

202 Accepted - uspješno otvoren zahtjev

400 Bad Request - pogrešno definiran POST upit

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

Accept: application/json
Content-Type: multipart/form-data

Parametri
bagit: test.zip

202 Accepted

HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

202 Accepted - uspješno otvoren zahtjev

400 Bad Request - pogrešno definiran POST upit

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

Accept: application/json

200 OK

{
  "pid": "fer:1234",
  "naslov": "Naslov",
  "datum_pohrane": "2015-10-12T14:38:30.862Z",
  "datum_zadnje_izmjene": "2016-04-26T06:31:47.609Z",
  "povezani_objekti": {
    "prilozi": [
      {
        "pid": "fer:2345"
      },
      {
        "pid": "fer:3456"
      }
    ]
  }
}

200 OK - uspješno dohvaćeni rezultati

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

404 Not Found - rad ne postoji u repozitoriju

Accept: application/json
Content-Type: multipart/form-data

Parametri
bagit: test.zip

202 Accepted

HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

202 Accepted - uspješno otvoren zahtjev

400 Bad Request - pogrešno definiran POST upit

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

Accept: application/json
Content-Type: multipart/form-data

Parametri
bagit: test.zip

202 Accepted

HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

202 Accepted - uspješno otvoren zahtjev

400 Bad Request - pogrešno definiran POST upit

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

Accept: application/json

200 OK

{
  "pid": "fer:2345",
  "nazlov": "Naslov",
  "datum_pohrane": "2015-10-12T14:38:30.862Z",
  "datum_zadnje_izmjene": "2016-04-26T06:31:47.609Z",
  "povezani_objekti": {
    "zavrsni": [
      {
        "pid": "fer:4567"
      },
      {
        "pid": "fer:5678"
      }
    ],
    "disertacije": [
      {
        "pid": "fer:6789"
      },
      {
        "pid": "fer:7891"
      }
    ]
  }
}

200 OK - uspješno dohvaćeni rezultati

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

404 Not Found - prilog ne postoji u repozitoriju 

Accept: application/json

200 OK

{
  "pid": "fer:1234",
  "naslov": "Naslov",
  "datum_pohrane": "2015-10-12T14:38:30.862Z",
  "datum_zadnje_izmjene": "2016-04-26T06:31:47.609Z",
  "povezani_objekti": {
    "prilozi": [
      {
        "pid": "fer:2345"
      },
      {
        "pid": "fer:3456"
      }
    ]
  }
}

200 OK - uspješno dohvaćeni rezultati

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

404 Not Found - rad ne postoji u repozitoriju

Accept: application/json
Content-Type: multipart/form-data

Parametri
bagit: test.zip

202 Accepted

HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

202 Accepted - uspješno otvoren zahtjev

400 Bad Request - pogrešno definiran POST upit

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

Accept: application/json
Content-Type: multipart/form-data

Parametri
bagit: test.zip

202 Accepted

HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

202 Accepted - uspješno otvoren zahtjev

400 Bad Request - pogrešno definiran POST upit

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

Accept: application/json

200 OK

{
  "kod": "1",
  "poruka": "Objekt je uspješno pohranjen u repozitorij",
  "opis_greske": null,
  "pid": "fer:1234",
  "vrijeme_zahtjeva": "2016-05-29 23:09:25",
  "resurs": "zavrsni"
}

200 OK - uspješno dohvaćene informacije o tijeku pohranjivanja

401 Unauthorized - korisničko ime i/ili lozinka su pogrešni

404 Not Found - objekt ne postoji u repozitoriju

Kod:
  1 Objekt je uspješno pohranjen/ažuriran
  2 Objekt je u procesu validacije i unosa/ažuriranja
  3 Objekt je na listi čekanja za izvršenje zahtjeva
  4 BagIt kontejner nije definiran u skladu sa standardom
  5 Nepotpuni podaci dostavljeni BagIt kontejnerom
  6 Nema aktivnih zahtjeva