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.

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.

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

{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

Opis strukture

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.

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

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.

Specifikacija metapodataka (MODS)

Opća definicija XML datoteke 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:

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

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

Kratki pregled odabranog završnog, specijalističkog ili diplomskog rada

Osnovne informacije o odabranom završnom, specijalističkom ili diplomskom radu.

Parametri
Varijabla opis
pid Jedinstveni identifikator rada u repozitoriju

Polja u zaglavlju (header)

Accept: application/json

Primjer rezultata

GET https://repozitorij.fer.unizg.hr/api/zavrsni/fer:1234

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"
      }
    ]
  }
}

Povratni statusi i poruke

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

Otvaranje zahtjeva za pohranjivanje završnog, specijalističkog ili diplomskog rada

Zaprimanje BagIt kontejnera i početak pohrane završnog, specijalističkog ili diplomskog rada s eventualnim prilozima. Status pohrane se dalje može pratiti na /zahtjevi/{pid}.

Polja u zaglavlju (header)

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

Polja u tijelu (body)

Varijabla opis
Parametri

bagit
Tip polja: file

BagIt .zip datoteka

Primjer rezultata

POST https://repozitorij.fer.unizg.hr/api/zavrsni

Parametri
bagit: test.zip
202 Accepted
HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

Povratni statusi i poruke

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

Otvaranje zahtjeva za ažuriranje završnog, specijalističkog ili diplomskog rada

Slanje podataka potrebnih za ažuriranje završnog, specijalističkog ili diplomskog rada s eventualnim prilozima. Stari rad ostaje isti ako je u proces ažuriranja zaustavljen zbog neke od grešaka. Uz rad se vežu samo dostavljeni prilozi iz BagIt kontejnera.

Polja u zaglavlju (header)

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

Polja u tijelu (body)

Varijabla opis
Parametri

bagit
Tip polja: file

BagIt .zip datoteka

Primjer rezultata

PUT https://repozitorij.fer.unizg.hr/api/zavrsni/fer:1234

Parametri
bagit: test.zip
202 Accepted
HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

Povratni statusi i poruke

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

Kratki pregled odabrane disertacije ili znanstvenog magistarskog rada

Osnovne informacije o odabranoj disertaciji ili znanstvenom radu.

Parametri
Varijabla opis
pid Jedinstveni identifikator rada u repozitoriju

Polja u zaglavlju (header)

Accept: application/json

Primjer rezultata

GET https://repozitorij.fer.unizg.hr/api/disertacije/fer:1234

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"
      }
    ]
  }
}

Povratni statusi i poruke

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

Otvaranje zahtjeva za pohranjivanje disertacije ili znanstvenog magistarskog rada

Zaprimanje BagIt kontejnera i početak pohrane disertacije ili znanstvenog magistarskog rada s eventualnim prilozima. Status pohrane se dalje može pratiti na /zahtjevi/{pid}.

Polja u zaglavlju (header)

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

Polja u tijelu (body)

Varijabla opis
Parametri

bagit
Tip polja: file

BagIt .zip datoteka

Primjer rezultata

POST https://repozitorij.fer.unizg.hr/api/disertacije

Parametri
bagit: test.zip
202 Accepted
HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

Povratni statusi i poruke

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

Otvaranje zahtjeva za ažuriranje disertacije ili znanstvenog magistarskog rada

Dohvaćanje podataka potrebnih za ažuriranje disertacije ili znanstvenog magistarskog rada s eventualnim priozima. Stari rad ostaje isti ako je u proces ažuriranja zaustavljen zbog neke od grešaka. Uz rad se vežu samo dostavljeni prilozi iz BagIt kontejnera.

Polja u zaglavlju (header)

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

Polja u tijelu (body)

Varijabla opis
Parametri

bagit
Tip polja: file

BagIt .zip datoteka

Primjer rezultata

PUT https://repozitorij.fer.unizg.hr/disertacije/fer:1234

Parametri
bagit: test.zip
202 Accepted
HEADER:
Location: https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

Povratni statusi i poruke

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

Kratki pregled odabranog priloga uz neki od radova

Osnovne informacije o odabranom prilogu.

Parametri
Varijabla opis
pid Jedinstveni identifikator priloga u repozitoriju

Polja u zaglavlju (header)

Accept: application/json

Primjer rezultata

GET https://repozitorij.fer.unizg.hr/api/prilozi/fer:2345

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"
      }
    ]
  }
}

Povratni statusi i poruke

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

Status zahtjeva

Dohvaćanje informacija o tijeku izvršavanja zahtjeva. Prikazuju se zahtjevi nastali zadnjih 48 sati.

Polja u zaglavlju (header)

Accept: application/json

Polja u tijelu (body)

Parametri
Varijabla opis
pid Privremeni identifikator objekta u repozitoriju

Primjer rezultata

GET https://repozitorij.fer.unizg.hr/api/zahtjevi/fer:1234

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"
}

Povratni statusi i poruke

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