-
Notifications
You must be signed in to change notification settings - Fork 26
ClientAPIDEV
Popis klientského API.
Cílem je vytvořit ucelené API, pomocí kterého je možno vytvářet nové alternativní klienty pro systém K5. API by mělo pokrývat veškerou funkcionalitu klientské části, případně část část administrace.
Implementačně se vychází z [RemoteAPI] a to je obohacováno o nové zdroje nesoucí informace o zobrazovaných titulech. Standardním formátem je JSON, při získávání xml metadat (mods, dc) pak xml.
První implementace samostatného klienta pracující nad tímto api vznikla pro system ČDK (http://cdk.lib.cas.cz/client/) a je součástí instalace systému Kramerius. Toto API dále využívají mobilní aplikace pro Android a iOS a web digitalniknihovna.cz.
Základní bod - nese informace o zobrazovaném titulu.
Příklad použítí:
GET http://localhost:8080/search/api/v5.0/item/<pid>
Příklad výstupu:
{
// identifikator zobrazovaneho pidu
"pid": "uuid:ef065970-8137-11e0-85ae-000d606f5dc6",
// model
"model": "page",
// titulek
"title": [
1
],
// titulek korenoveho periodika (pripadne monografie)
"root_title": "Dějiny a současnost",
// identifikator korenoveho periodika
"root_pid": "uuid:045b1250-7e47-11e0-add1-000d606f5dc6",
// kontext
"context": [
[
{
"pid": "uuid:045b1250-7e47-11e0-add1-000d606f5dc6",
"model": "periodical"
},
{
"pid": "uuid:f7e50720-80b6-11e0-9ec7-000d606f5dc6",
"model": "periodicalvolume"
},
{
"pid": "uuid:91214030-80bb-11e0-b482-000d606f5dc6",
"model": "periodicalitem"
},
{
"pid": "uuid:ef065970-8137-11e0-85ae-000d606f5dc6",
"model": "page"
}
]
],
// datový uzel - krom metadata nese i samotná data - obrázek
"datanode": false,
// pro zobrazovaný titul je možno použít deep zoom prohlížečku
"zoom": {
"url": "http://localhost:8080/search/deepZoom/uuid:ef065970-8137-11e0-85ae-000d606f5dc6",
"type": "deepzoom"
},
// pokud by stream IMG_FULL obsahoval pdf, byl by přítomen klíč pdf
//"pdf": {
// "url": "http://localhost:8080/search/....",
//},
// titul je součástí sbírky
"collections": [
"vc:f73dee31-ae76-4dbc-b7b9-d986df497596"
],
// titul byl pořízen replikací
"replicatedFrom": [
// první zdroj - originál
"http://kramerius.mzk.cz/search/handle/uuid:ef065970-8137-11e0-85ae-000d606f5dc6",
// druhý zdroj - replikovaná kopie
"http://cdk-test.lib.cas.cz/search/handle/uuid:ef065970-8137-11e0-85ae-000d606f5dc6"
]
}
Všechny děti titulu lze získat lze následujícím příkazem:
GET http://localhost:8080/search/api/v5.0/item/<pid>/children
Výstup je pak něco chudší - významy jednotlivých polí jsou stejné jako v příkladu výše:
[
{
"pid": "uuid:8a7275dc94169922a1f40df034a7e472",
"model": "page",
"title": [
"1a"
],
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:5fd94d78af7144f1fd358c9349646c4a",
"model": "page",
"title": [
"1b"
],
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:8ad841cbe186b70f9f5b5eb93fe290e0",
"model": "page",
"title": [
1
],
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:7372518643701c20d68f84285837eb61",
"model": "page",
"title": [
2
],
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:4307336f7ea25505183fabbc8e372452",
"model": "page",
"title": [
3
],
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:c6fff382591cf68cbd1564c88c910771",
"model": "page",
"title": [
4
],
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:18ad1fbded2a049a75a6c75b75a5ccf2",
"model": "page",
"title": "5",
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:34c887471b26108511fa149c113e555e",
"model": "page",
"title": "6",
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:79a94f58703a27af808264f0f355e72a",
"model": "page",
"title": "7",
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:eadf3e5f41512b22f9f677ae66143e12",
"model": "page",
"title": "8",
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:381a713aac0784e32cba1fe113fa701f",
"model": "page",
"title": "9",
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
{
"pid": "uuid:828faee31b7d47a741eb486d60b977fe",
"model": "page",
"title": "10",
"root_title": "Sborník příspěvků k dějinám a výstavbě Brna",
"root_pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"datanode": false
},
....
Získání sourozenců vypadá následovně:
GET http://localhost:8080/search/api/v5.0/item/<pid>/siblings
Výstup:
[
{
"path": [
{
"pid": "uuid:ec78e650-298d-11e2-9f39-005056827e51",
"model": "periodical"
},
{
"pid": "uuid:bc045b40-2efa-11e2-9975-005056825209",
"model": "periodicalvolume"
},
{
"pid": "uuid:c32e0540-3e38-11e2-8227-5ef3fc9bb22f",
"model": "periodicalitem"
}
],
// sourozenci
"siblings": [
{
"pid": "uuid:c32e0540-3e38-11e2-8227-5ef3fc9bb22f",
"model": "periodicalitem",
// dotazovaný uzel
"selected": true
},
{
"pid": "uuid:c32e0540-3e38-11e2-8227-5ef3fc9aa22f",
"model": "periodicalitem",
"selected": false
}
]
}
]
Poznámka: Výstupem je pole objektů. Každý z nich obsahuje klíč path
, tam je definovaná cesta k uzlu, a klíč siblings
obsahující samotné sourozence požadovaného objektu. Zprávu nejlépe popíšu příkladem: Mějme objekt typu stránka, která je součástí periodika a zároveň součástí článku. V tomto případě by výsledný json obsahoval pole o dvou objektech. První by reprezentoval sourozence pro článek, druhý pro výtisk periodika.
Data jsou uložena v datových streamech. Viz datový model. Seznam datových streamů lze získat následujícím:
GET http://localhost:8080/search/api/v5.0/item/<pid>/streams
Výstup:
{
"DC": {
"label": "Dublin Core Record for this object",
"mimeType": "text/xml"
},
"BIBLIO_MODS": {
"label": "BIBLIO_MODS description of current object",
"mimeType": "text/xml"
}
}
GET http://localhost:8080/search/api/v5.0/item/<pid>/streams/<stream_id>
Výstup bude odpovídat datům ze streamu (stejně tak i MIME-TYPE odpovědi). Nutno podotknout, že v tomto případě jsou na chráněné streamy aplikována práva.
Obrazové streamy lze krom výše uvedené postupu ještě získat následujícím:
GET http://localhost:8080/search/api/v5.0/item/<pid>/full
GET http://localhost:8080/search/api/v5.0/item/<pid>/preview
GET http://localhost:8080/search/api/v5.0/item/<pid>/thumb
Výsledkem jsou data ze streamů IMG_FULL, IMG_PREVIEW a IMG_THUMB. Na rozdíl od výše popsaného způsobu, tyto metody přesměrují na servlet, který umí projít strom a podat obrázek i pro objekt, který nenese data (nemá IMG_FULL, IMG_PREVIEW nebo IMG_THUMB).
GET http://localhost:8080/search/api/v5.0/item/<pid>/foxml
Vrátí plný foxml objekt pokud má dotazovaný právo číst. V opačném případě vrátí status 403 access denied.
Pro lepší orientaci a experimenty je připravena testovací třída:
Zdroj pro vyhledávání. Dotazuje přímo SOLR a data modifikuje tak, aby neobsahovala chráněná data (pole text_ocr a text) a přeposílá ve formátu SOLRU.
Ukázka dotazu:
GET http://localhost:8080/search/api/v5.0/search?q=*:*
Výsledek může být ve formátu JSON nebo XML (standardně), popis standardně krameriem definovaných polí je zde ...
Ukázka dotazu pro JSON:
curl -H "Accept: application/json" http://krameriusdemo.mzk.cz/search/api/v5.0/search?q=*:*
Třída pro testy:
Vrací JSON s aktuální nakonfigurovanou hodnotou generatePdfMaxRange a hodnotou boolean, která indikuje, zda je limit uplatňován.
Volání:
GET http://localhost:8080/search/api/v5.0/pdf/conf
Výstup:
{"maxpage":"1800","turnOffPdfCheck":false}
Vrací vybrané strany na základě seznamu PID. Seznam je ve tvaru řetězce identifikátorů oddělených čárkou.
Příklad:
GET http://localhost:8080/search/api/v5.0/pdf/selection?pids=uuid:ee78ecb0-2af3-11e5-8454-005056825209,uuid:ee898e80-2af3-11e5-8454-005056825209
Dále je možné specifikovat způsob vygenerování první strany parametrem firstPageType s hodnotou TEXT nebo IMAGES; implicitní varianta první strany je textová.
Příklad:
GET http://localhost:8080/search/api/v5.0/pdf/selection?pids=uuid:ee78ecb0-2af3-11e5-8454-005056825209,uuid:ee898e80-2af3-11e5-8454-005056825209&firstPageType=IMAGES
Dalším parametrem je language, kterým se vybere text hlavičky (texts/first_page_nolines_xml) a texty labelů (base.properties). Podporované hodnoty jsou cs (texts/first_page_nolines_xml_CZ_cs a base_cs.properties) pro češtinu a en (texts/first_page_nolines_xml_EN_en a base_en.properties) pro angličtinu. Pokud není uvedeno, je použita defaultní lokalizace (český texts/first_page_nolines_xml a anglický base.properties).
Příklad:
GET http://localhost:8080/search/api/v5.0/pdf/selection?pids=uuid:ee78ecb0-2af3-11e5-8454-005056825209,uuid:ee898e80-2af3-11e5-8454-005056825209&language=en
Vrací rozsah stran na základě identifikátoru rodičovského elementu, parametru number, který určuje počet stran, případně i nepovinného parametru offset.
Příklad:
GET http://localhost:8080/search/api/v5.0/pdf/parent?pid=uuid:972d5ee0-bd94-11e4-9541-005056827e51&number=5
Je možné specifikovat způsob vygenerování první strany (viz oddíl Vybrané strany)
Vrací identifikátor handle k vygenerovanému PDF.
Příklad:
GET http://localhost:8080/search/api/v5.0/asyncpdf/parent?pid=uuid:972d5ee0-bd94-11e4-9541-005056827e51&number=5
Výstup:
{"handle":"18120687-8bd0-4903-b822-bd05a6786cbb"}
Je možné specifikovat způsob vygenerování první strany (viz PDFResource - Vybrané strany)
Na základě handle identifikártoru vrací vygenerované PDF.
Příklad:
GET http://localhost:8080/search/api/v5.0/asyncpdf/handle?handle=18120687-8bd0-4903-b822-bd05a6786cbb
Slouží pro získávání informací o nejoblíbenějších a nejnovějších titulech.
Ukázka dotazu:
GET http://localhost:8080/search/api/v5.0/feed/mostdesirable
Výstup:
{
// odkaz na rss feed
"rss": "http://localhost:8080/search/inc/home/mostDesirables-rss.jsp",
// samotna json data
"data": [
{
"pid": "uuid:045b1250-7e47-11e0-add1-000d606f5dc6",
"model": "periodical",
"title": "Dějiny a současnost",
"root_title": "Dějiny a současnost",
"root_pid": "uuid:045b1250-7e47-11e0-add1-000d606f5dc6",
"context": [
[
{
"pid": "uuid:045b1250-7e47-11e0-add1-000d606f5dc6",
"model": "periodical"
}
]
],
"datumstr": "",
"issn": "0862-6111",
},
...
Dotaz je možno filtrovat dle modelu a definovat počet výsledků a offset. Příklad:
GET http://localhost:8080/search/api/v5.0/feed/mostdesirable?type=page&limit=3&offset=0
Ukázka dotazu:
GET http://localhost:8080/search/api/v5.0/feed/newest
Výstup:
{
"rss": "http://localhost:8080/search/inc/home/newest-rss.jsp",
"data": [
{
"pid": "uuid:84f0c6c0-3c39-11e1-b83b-0013d398622b",
"model": "monograph",
"title": "30 let hercem",
"root_title": "30 let hercem",
"root_pid": "uuid:84f0c6c0-3c39-11e1-b83b-0013d398622b",
"context": [
[
{
"pid": "uuid:84f0c6c0-3c39-11e1-b83b-0013d398622b",
"model": "monograph"
}
]
],
"datumstr": "1946",
"issn": "",
},
...
Dotaz je možno filtrovat dle modelu a definovat počet výsledků a offset. Příklad:
GET http://localhost:8080/search/api/v5.0/feed/newest?type=page&limit=3&offset=0
Ukázka dotazu:
GET http://localhost:8080/search/api/v5.0/feed/custom
Výstup:
{
"data": [
{
"pid":"uuid:530719f5-ee95-4449-8ce7-12b0f4cadb22",
"model":"monograph","root_pid":"uuid:530719f5-ee95-4449-8ce7-12b0f4cadb22",
"title":"Když slunéčko svítí : verše","root_title":"Když slunéčko svítí : verše",
"author":["Rais, Karel Václav"],
"policy":"public"
},
...
Dotaz lze omezit typem dokumentu a dostupností. Příklad:
GET http://localhost:8080/search/api/v5.0/feed/custom?type=monograph&policy=public
Třída pro testy:
Umožňuje získat informace o uživateli, získat jeho profil, měnit ho případně měnit jeho heslo.
Příklad dotazu
GET http://localhost:8080/search/api/v5.0/user
Výstup:
{
"firstname": "kramerius",
"surname": "admin",
"lname": "krameriusAdmin",
"roles": [
{
"name": "k4_admins"
},
{
"name": "common_users"
}
]
}
Poznámka, tohoto dotazu lze i v klientských aplikacích využít pro ověření autentizačních údajů. Pokud jsou chybě zadané, výstup bude stejný jako kdyby autentizační hlavička úplně chyběla:
{
"firstname": "not_logged",
"surname": "not_logged",
"lname": "not_logged",
"roles": [
{
"name": "common_users"
}
]
}
Pro změnu hesla je nutno využít metodu post
, který bude mít obsah dotazu JSON objekt s klíčem pswd
obsahující nové heslo.
POST http://localhost:8080/search/api/v5.0/user
Tělo dotazu:
{
"pswd": "xxx23abxx",
}
Získání profilu:
GET http://localhost:8080/search/api/v5.0/user/profile
Výstup:
{
"searchHistory": [
{
"url": "http://localhost:8080/search/r.jsp?offset=0&forProfile=facet&fq=document_type:%22monograph%22",
"rss": "http://localhost:8080/search/r-rss.jsp?offset=0&forProfile=facet&fq=document_type:%22monograph%22",
"fq": [
"document_type:\"monograph\""
]
},
...
]
}
Změna profilu je realizována metodou post
. Obsahem dotazu je JSON reprezentující nový profil.
POST http://localhost:8080/search/api/v5.0/user/profile
Testovací třída:
Slouží k získání informací o virtuálních sbírkách
GET http://localhost:8080/search/api/v5.0/vc
Výstup:
[
{
"pid": "vc:f73dee31-ae76-4dbc-b7b9-d986df497596",
"label": "vc:f73dee31-ae76-4dbc-b7b9-d986df497596",
"canLeave": true,
"descs": {
"en": "ACADEMIA",
"cs": "AKADEMIA"
}
}
]
Výstup je možno získat setříděný a to pomocí parametrů sort
a langCode
. Sestupně setříděný výstup podle českého pokisku je možno dostat následovně:
GET http://localhost:8080/search/api/v5.0/vc?sort=DESC&langCode=cs
Info o jedné sbírce:
GET http://localhost:8080/search/api/v5.0/vc/<pid>
Výstup:
[
{
"pid": "vc:f73dee31-ae76-4dbc-b7b9-d986df497596",
"label": "vc:f73dee31-ae76-4dbc-b7b9-d986df497596",
"canLeave": true,
"descs": {
"en": "ACADEMIA",
"cs": "AKADEMIA"
}
}
]
Testovací třída:
VirtualCollectionsResourceClient.java
Slouží k získávání informací o právech pro aktuálního uživatele.
Volání:
GET http://localhost:8080/search/api/v5.0/rights
Zobrazí práva pro aktuálního uživatele, všechny akce a objekt REPOSITORY viz [Prava].
Výstup:
{
"read": true,
"import": false,
"convert": false,
"replicationrights": false,
"enumerator": false,
"reindex": false,
"replikator_periodicals": false,
"replikator_monographs": false,
"replikator_k3": false,
"delete": false,
"export": false,
"setprivate": false,
"setpublic": false,
"administrate": false,
"editor": false,
"manage_lr_process": false,
"export_k4_replications": false,
"import_k4_replications": false,
"export_cdk_replications": false,
"edit_info_text": false,
"rightsadmin": false,
"rightssubadmin": false,
"virtualcollection_manage": false,
"criteria_rights_manage": false,
"ndk_mets_import": false,
"display_admin_menu": false,
"aggregate": true,
"show_statictics": false,
"sort": true,
"show_print_menu": false
}
Práva pro vybraný objekt a vybrané akce:
GET http://localhost:8080/search/api/v5.0/rights?actions=read,administrate&pid=uuid:ec78e650-298d-11e2-9f39-005056827e51
Výstup:
{
"read": true,
"administrate": false
}
Tato část obsahuje zdroje, které vyžadují autorizaci a jsou chráněny právy.
Umožňuje administraci uživatelů
GET http://localhost:8080/search/api/v5.0/admin/users
Výstup:
[
{
"lname": "krameriusAdmin",
"firstname": "kramerius",
"surname": "admin",
"id": 1,
"roles": [
{
"name": "k4_admins",
"id": 2
}
]
},
GET http://localhost:8080/search/api/v5.0/admin/users/<id>
Výstup:
{
"lname": "krameriusAdmin",
"firstname": "kramerius",
"surname": "admin",
"id": 1,
"roles": [
{
"name": "k4_admins",
"id": 2
}
]
}
POST http://localhost:8080/search/api/v5.0/admin/users/
Dotaz musí obsahovat data o uživateli obohacené o klíč password
.
PUT http://localhost:8080/search/api/v5.0/admin/users/
Dotaz musí obsahovat data o uživateli. Tímto způsobem je možno měnit klíče : firstname
, surname
a roles
. Ostatní klíče měnit nejdou.
DELETE http://localhost:8080/search/api/v5.0/admin/users/<id>
Výstupem je JSON reprezentující uživatele obohacený klíčem deleted
nastaveným na příznak true
.
Podobný přístup jako u UsersResource
GET http://localhost:8080/search/api/v5.0/admin/roles
Výstup :
[
{
"name": "k4_admins",
"id": 2
},
...
GET http://localhost:8080/search/api/v5.0/admin/roles/<id>
Výstup :
{
"name": "k4_admins",
"id": 2
}
DELETE http://localhost:8080/search/api/v5.0/admin/roles/<id>
Výstupem je JSON reprezentující roli obohacený klíčem deleted
nastaveným na příznak true
.
Testovací třída:
Slouží pro administraci práv
Výpis všech práv:
GET http://localhost:8080/search/api/v5.0/admin/rights
Výstup:
[
{
"id": 3,
"action": "import",
"pid": "uuid:1",
"role": {
"id": 2,
"name": "k4_admins"
}
},
{
"id": 4,
"action": "convert",
"pid": "uuid:1",
"role": {
"id": 2,
"name": "k4_admins"
}
},
{
"id": 5,
"action": "replicationrights",
"pid": "uuid:1",
"role": {
"id": 2,
"name": "k4_admins"
}
},
// priklad s kriteriem
{
"id": 41,
"action": "read",
"pid": "uuid:0eaa6730-9068-11dd-97de-000d606f5dc6",
"role": {
"id": 1,
"name": "common_users"
},
"criterium": {
"qname": "cz.incad.kramerius.security.impl.criteria.Window",
"params": {
"id": 3,
"ldesc": "",
"sdesc": "rokyoddo",
"objects": [
"1022",
"1980"
]
}
}
},
......
Získání jednoho záznamu práva:
GET http://localhost:8080/search/api/v5.0/admin/rights/<id>
Výstup je stejný jako u příkladu výše.
Vytvoření nového práva:
POST http://localhost:8080/search/api/v5.0/admin/rights
Jako hodnota dotazu je json objekt obsahující zakládané právo. Výsledkem je vytvořené právo.
Smazání práva:
DELETE http://localhost:8080/search/api/v5.0/admin/rights/<id>
Výpis všech parametrů:
GET http://localhost:8080/search/api/v5.0/admin/rights/params
Výstup:
[
{
"id": 1,
"ldesc": "",
"sdesc": "Localhosts",
"objects": [
"127.*",
"localhost",
"0.*"
]
},
{
"id": 3,
"ldesc": "",
"sdesc": "rokyoddo",
"objects": [
"1022",
"1980"
]
},
Jeden parametr:
GET http://localhost:8080/search/api/v5.0/admin/rights/params/<id>
Vytvoření nového:
POST http://localhost:8080/search/api/v5.0/admin/rights/params
Smazání existujícího:
DELETE http://localhost:8080/search/api/v5.0/admin/rights/params/<id>
Testovací třída:
Zdroj umožňuje správu virtuálních sbírek.
GET http://localhost:8080/search/api/v5.0/admin/vc
Výstup je stejný jako u klientské části.
GET http://localhost:8080/search/api/v5.0/admin/vc/<pid>
Výstup je stejný jako u klientské části.
Poznámka: Virtuální sbírka je objekt v repositáři, lze na něj uplatnit dotazy stejné jako na položku item:
GET http://localhost:8080/search/api/v5.0/item/<pid>
GET http://localhost:8080/search/api/v5.0/item/<pid>/streams
atd..
DELETE http://localhost:8080/search/api/v5.0/admin/vc/<pid>
Výstup je stejný jako u klientské části obohacený o klíč deleted
nastaveným na příznak true
.
Testovací třída: