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.

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