Open social widget project Metis resource interface Versie 0.5 7 mei 2010
Page 2 of 7
1. Over dit document Dit document beschrijft de restful service interface van Metis. Deze interface wordt geregeld uitgebreid en het is daarom aan te raden de laatste versie van deze documentatie te gebruiken. 1.1 Document historie versie auteur datum Opmerkingen 0.1 Gerbrand ten Napel 12-03-2010 Eerste voorstel 0.2 Gerbrand ten Napel 01-04-2010 Paginering toegevoegd 0.3 Gerbrand ten Napel 07-04-2010 Eerste online versie 0.4 Gerbrand ten Napel 23-04-2010 Aanpassing paging api 0.5 Gerbrand ten Napel 07-05-2010 Aanpassing n.a.v. opm. Maurice 2. Http header parameters Alle resources zijn te benaderen met http GET. Vooralsnog geven we in alle gevallen JSON terug, in de toekomst zullen we reageren op 3 content types: Content-Type: text/html; charset=utf-8 Content-Type: text/xml; charset=utf-8 Content-Type: text/json; charset=utf-8 Taalkeuze gaat via een language parameter:?language=nl voor Nederlands en?language=en (en alle andere waarden) voor Engels Page 3 of 7
3. Resource identificatie We onderscheiden de volgende resources: instelling, researcher, result, results, apa, resultcategories. Alle urls zijn in kleine letters. 3.1 Overzicht url opbouw Hieronder een overzicht van de url opbouw met daarbij de huidige 4 GET request mogelijkheden. Page 4 of 7
3.2 Toelichting api url s Hieronder volgt een toelichting op de bovengenoemde 4 request mogelijkheden met daarbij voorbeelden van GET-requests en response. Top level resource De api root begint bij de instellingsnaam: http://metis-api.domein /[instelling]/ Voor test is dit bijvoorbeeld: http://tetris.uci.ru.nl:8080/eur/ (get request hierop heeft geen functie). Resultaten Hieronder volgen de 4 url s die aan te roepen zijn. In het geval een response bestaat uit een lijst met resultaten is de sorteervolgorde als volgt: 1. resultcategory (in volgorde zoals aangegeven in de metis tabel all_klas_groep) 2. year aflopend 3. titel van het resultaat, hoofdletter-ongevoelig en ontdaan van lidwoorden e.d. De volgende resource url s zijn voor resultaten beschikbaar: 1. /eur/researcher/dai/[nr]/results/ [?resultcategory=] [?period=] Met deze url is een lijst met alle resultaten van een onderzoeker op te vragen. Resultcategory (id) en period zijn mogelijke parameters die als filter zijn te gebruiken. Daarbij bestaat period uit 2 vier-cijferige jaartallen: beginjaar tot en met eindjaar, gescheiden door een komma (zie voorbeeld 3). Voorbeeld 1, alle resulaten Alle resultaten van onderzoeker met DAI 189852119 : /eur/researcher/dai/189852119/results/ Een get request op deze url geeft een lijst met daarin id s en url s naar resultaten, In JSON levert dit: [ { id : 146550, url : http://../eur/result/resultid/146550/ }, { id : 140430, url : http://../eur/result/140430/ } ] In XML zal dit geven: <results> <result><id>146550</id><url>http://../eur/result/resultid/146550/</url></result> <result><id>140430</id><url>http://../eur/result/ resultid/140430/</url></result> </results> Page 5 of 7
Voorbeeld 2, resulaten in een categorie Alle resultaten van onderzoeker met DAI 189852119 in de categorie Wetenschappelijke publicatie (id 2): /eur/researcher/dai/189852119/results?resultcategory=2 In JSON levert dit toevallig ook: [ { id : 146550, url : http://../eur/result/resultid/146550/ }, { id : 140430, url : http://../eur/result/140430/ } ] Voorbeeld 3, resulaten in een categorie en periode Alle resultaten van onderzoeker met DAI 189852119 in de categorie 2 van 1995 tot en met 2010: /eur/researcher/dai/492564/results?resultcategory=2&period=1995,2010 2. /eur/researcher/dai/[nr]/results/ page/1/size/10 [?resultcategory=] [?period=] Met deze url kunnen resultaten per pagina worden opgehaald. De url [instelling]/results/page/[n]/size/[y] geeft de n-e pagina met daarop maximaal y resultaten. Het kan dus zijn dat zo n pagina minder dan y resultaten of géén resultaten bevat. We beginnen bij 1 te tellen. Voorbeeld 1 De eerste 10 resultaten van onderzoeker met DAI 189852119 /eur/researcher/dai/ 189852119/results/page/1/size/10 In JSON geeft dit: [ { id : 85463, url : http://../eur/result/85463/, resultcategory : w, year : 2001, result : Boer, H.D. de, Esmond, J. van, Booij.. }, }] Hierbij geldt: - url: link naar het resultaat (vooralsnog alleen te gebruiken door er "/apa" achter te plakken). - id: metis resultaat id. - resultcategory: id van de resultaatcategorie - year: jaar van uitgave van het resultaat (als dit in Metis niet is opgegeven betreft dit het verslagjaar) - result: het resultaat weergegeven in apa formaat. NB: dit kan html bevatten (italic-tags en een link naar de full-text) Page 6 of 7
Voorbeeld 2 Resultaten 21 tm 30 van onderzoeker met DAI 492564 in de categorie2 /eur/researcher/dai/492564/results/page/3/size/10?resultcategory=2 3. /eur/result/resultid/[nr]/apa/ Met deze url is een resultaat opgemaakt in apa formaat op te vragen. Voorbeeld 1 Resultaat met volgnummer 146550 in APA: /eur/result/resultid/146550/apa In JSON geeft dit: { result : Boer, H.D. de, Esmond, J. van, Booij, L.H.D.J. & Driessen, J.J. (2009). Reversal of rocuronium-induced profound neuromuscular block by sugammadex in Duchenne muscular dystrophy. <i> Paediatr Anaesth </i>, 19(12), 1226-8. } 4. /eur/resultcategories/ Deze url geeft alle resultaat categorieën van de instelling, In JSON geeft dit: [ { id : D, name : Dissertatie }, { id : W, name : Wetenschappelijke publicatie }, }] Page 7 of 7