Versjon 2.4
Innledning
Tjenesten er designet etter en RPC[1] modell over HTTP. Hver tjeneste er en “funksjon” som kjøres vha. GET og som tar parametere i form av “query parameters”. Svar blir levert i XML eller JSON format. Dersom tjenesten returnerer et bilde, blir det levert i JPEG format. Dersom et søk gir over 1000 treff ansees dette som en feilsituasjon. Man kan da begrense søket ytterligere og prøve igjen.
HTTP-feilkode | Forklaring |
---|---|
400 | En ugyldig parameterkombinasjon er angitt eller påkrevede parametere er utelatt. |
404 | Søket ga ingen treff |
413 | Søket er for vidt til at tjenesten kan returnere et svar[2]. |
500 | En feil oppstod på serveren. |
[1] Remote Procedure Call
[2] Dette er strengt tatt feil bruk av denne koden, men ingen annen kode passer bedre
Tjeneste 1: hentPerson
Beskrivelse:
Tjenesten henter ut opplysninger om en person som er registert i Cristin. Personen kan angis enten med (bruker)navn og eierkode eller med lopenr.
Basis-URL: /ws/hentPerson
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
eierkode | Streng | Kode som identifiserer organisasjonen hvor brukernavnet hører hjemme. Må brukes sammen med parameteren “navn”. |
navn | Streng | Brukernavn tiknyttet en organisasjon. Må brukes sammen med parameteren “eierkode”. |
lopenr | Heltall | Unik id for en person i Frida- systemet. Må ikke brukes sammen med parameterne “navn” og “eierkode”. |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
Eksempler:
- http://cristin.no/ws/hentPerson?lopenr=1479
- http://cristin.no/ws/hentPerson?navn=aal041&eierkode=UIB
- http://cristin.no/ws/hentPerson?navn=aaboen&eierkode=UIO
Tjeneste 2: hentPersonSted
Beskrivelse:
Henter ut personer tilknyttet et sted.
Basis-URL: /ws/hentPersonSted
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
instnr | Heltall | Institusjonsnummer brukt i Cristin. (påkrevet) |
avdnr | Heltall | Avdelingsnummer (valgfri) |
undavdnr | Heltall | Underavdelingsnummer (valgfri) |
gruppenr | Heltall | Gruppenummer (valgfri) |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
sortering | Streng | Prioritert sorteringsrekkefølge, spesifisert med en av disse strengene: STED |
Eksempler:
- http://cristin.no/ws/hentPersonSted?instnr=185&avdnr=14&undavdnr=3&gruppenr=0
- http://cristin.no/ws/hentPersonSted?instnr=185&avdnr=14&undavdnr=3
Tjeneste 3: hentPersonBilde
Beskrivelse:
Henter ut en persons bilde. Personen kan angis enten med navn og eierkode eller med lopenr.
Basis-URL: /ws/hentPersonBilde
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
eierkode | Streng | Kode som identifiserer organisasjonen hvor brukernavnet hører hjemme. Må brukes sammen med parameteren “navn”. |
navn | Streng | Brukernavn tiknyttet en organisasjon. Må brukes sammen med parameteren “eierkode”. |
lopenr | Helltall | Unik id for en person i Cristin- systemet. Må ikke brukes sammen med parameterne “navn” og “eierkode”. |
Eksempler:
- http://cristin.no/ws/hentPersonBilde?lopenr=24679
- http://cristin.no/ws/hentPersonBilde?navn=nilsst&eierkode=UIO
Tjeneste 4: hentVarbeiderPerson
Beskrivelse:
Henter ut vitenskapelige arbeider tilknyttet en person.
Basis-URL: /ws/hentVarbeiderPerson
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
eierkode | Streng | Kode som identifiserer organisasjonen hvor brukernavnet hører hjemme. Må brukes sammen med parameteren “navn”. |
navn | Streng | Brukernavn tiknyttet en organisasjon. Må brukes sammen med parameteren “eierkode”. |
lopenr | Heltall | Unik id for en person i Cristin- systemet. Må ikke brukes sammen med parameterne “navn” og “eierkode”. |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
fra | Heltall | Årstall. Tar kun med arbeider utgitt fra og med dette året. (valgfri) |
til | Heltall | Årstall. Tar kun med arbeider utgitt til og med dette året. (valgfri) |
utplukk | Streng | En av “alle”, “nyeste”, “viktigste” (valgfri, “alle” er default). “nyeste” og “viktigste” må brukes sammen med parameteren “maksantall”. * |
maksantall | Heltall | Maks antall treff som skal returneres. Må kun brukes sammen med utplukk=viktigst eller utplukk=nyeste. |
hovedkategori | Streng | Ta kun med treff fra denne hovedkategorien (valgfri). Se Tabell 1: Hovedkategorier per 2011 |
Underkategori | Streng | Ta kun med treff fra denne underkategorien (valgfri) Se Tabell 2: Underkategorier per 2011 |
Sortering | Streng | Prioritert sorteringsrekkefølge, spesifisert med en av disse strengene: PERSON_TITTEL, AAR_PERSON_TITTEL, HOVEDKAT_PERSON_TITT EL, UNDERKAT_PERSON_TITT EL |
* Nyeste referer til de sist registrerte og redigerte vitenskapelige arbeidene. Viktigste referer til publikasjoner som er lagt til som Hovedpublikasjoner i forskerprofilen.
Eksempler:
- http://cristin.no/ws/hentVarbeiderPerson?navn=nilsst&eierkode=UIO&fra=2008&til=2010
- http://cristin.no/ws/hentVarbeiderPerson?navn=nilsst&eierkode=UIO&fra=2004&til=2010&hovedkategori=BOK
Tjeneste 5: hentVarbeidSted
Beskrivelse:
Henter ut vitenskapelige arbeider tilknyttet et sted.
Basis-URL: /ws/hentVarbeidSted
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
instnr | Heltall | Institusjonsnummer brukt i Cristin. (påkrevet) |
avdnr | Heltall | Avdelingsnummer (valgfri) |
undavdnr | Heltall | Underavdelingsnummer (valgfri) |
gruppenr | Heltall | Gruppenummer (valgfri) |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
fra | Heltall | Årstall. Tar kun med arbeider utgitt fra og med dette året. (valgfri) |
til | Heltall | Årstall. Tar kun med arbeider utgitt til og med dette året. (valgfri) |
utplukk | Streng | En av “alle”, “nyeste”, “viktigste” (valgfri, “alle” er default). “nyeste” og “viktigste” kan kun brukes i kombinasjon med parameteren “maksantall”. * |
maksantall | Heltall | Maks antall treff som skal returneres. Må kun brukes sammen med utplukk=viktigst eller utplukk=nyeste. |
hovedkategori | Streng | Ta kun med treff fra denne hovedkategorien (valgfri). Se Tabell 1: Hovedkategorier per 2011 |
underkategori | Streng | Ta kun med treff fra denne underkategorien (valgfri) Se Tabell 2: Underkategorier per 2011 |
sortering | Streng | Prioritert sorteringsrekkefølge, spesifisert med en av disse strengene: PERSON_TITTEL, AAR_PERSON_TITTEL, HOVEDKAT_PERSON_TITTEL, UNDERKAT_PERSON_TITTEL |
* Nyeste referer til de sist registrerte og redigerte vitenskapelige arbeidene. Viktigste referer til publikasjoner som er lagt til som Hovedpublikasjoner i forskerprofilen.
Eksempler:
Tjeneste 6: hentPresentasjon
Beskrivelse:
Henter ut en presentasjon basert på dens løpenr. Dersom type velges vil ingenting returneres hvis presentasjonen med det gitte løpenummeret er av en annen type enn den som er angitt.
Basis-URL: /ws/hentPresentasjon
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
lopenr | Heltall | Tall som identifiserer en presentasjon i Cristin. (påkrevet) |
type | Streng | Begrenser treff til presentasjoner av den typen angitt i Tabell 3: Presentasjonstyper. (valgfri) |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
Eksempler:
Presentasjonstype | Forklaring |
---|---|
PROSJEKT | Prosjekt |
GRUPPE | Forskningsgruppe |
ENHET | Organisasjonsenhet |
SENTER | Forskningssenter |
Tjeneste 7: hentPresentasjonSted
Beskrivelse:
Henter ut presentasjoner for et gitt sted, og av en gitt type.
Basis-URL: /ws/hentPresentasjonSted
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
instnr | Heltall | Institusjonsnummer brukt i Cristin. (påkrevet) |
avdnr | Heltall | Avdelingsnummer (valgfri) |
undavdnr | Heltall | Underavdelingsnummer (valgfri) |
gruppenr | Heltall | Gruppenummer (valgfri) |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
type | Streng | Begrenser treff til presentasjoner av den typen angitt i Tabell 3: Presentasjonstyper. (påkrevet) |
Eksempler:
Tjeneste 8: hentPresentasjonBilde
Beskrivelse:
Henter ut bilde/logo tilknyttet en presentasjon.
Basis-URL: /ws/hentPresentasjonBilde
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
lopenr | Heltall | Tall som identifiserer en presentasjon i Cristin. (påkrevet) |
Eksempler:
- http://cristin.no/ws/hentPresentasjonBilde?lopenr=49
- http://cristin.no/ws/hentPresentasjonBilde?lopenr=162
Tjeneste 9: hentProsjekter
Beskrivelse:
Returnerer prosjekter gitt Cristin prosjekt-id, ansvarlig sted, eller dato (endringerSiden). Bare publiserte prosjekter returneres (dvs. de med status_skal_vises = 'J' eller null, og status_publiserbar = 'J' eller null). Minst én av disse parametrene må oppgis: id, instnr, endringerSiden. Hvis ingen av de er gitt returneres 400 (Bad request). Ellers er parametrene valgfrie, og kan kombineres for å begrense søket (AND-funksjonalitet), f.eks. hvis både instnr og endringerSiden er oppgitt returneres prosjektene der institusjonen er ansvarlig sted og som er endret siden gitt dato. Hvis lopenr er oppgitt men prosjektet ikke finnes eller er ikke publisert returneres 404 (Not found). Hvis flere prosjekter matcher oppgitte parametre sorteres de fra nyeste opprettet til eldste.
Basis-URL: /ws/hentProsjekter
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
id | Heltall | Prosjektets unike løpenummer i tabellen (Cristin-prosjekt-id). Det kan kun medsendes ett løpenummer. (valgfri) |
instnr | Heltall | Institusjonsnr. for forskningsansvarlig sted. (valgfri) |
avdnr | Heltall | Avdelingsnr. for forskningsansvarlig sted. (valgfri) |
undavdnr | Heltall | Underavdelingsnr. for forskningsansvarlig sted. (valgfri) |
gruppenr | Heltall | Gruppenr. for forskningsansvarlig sted. (valgfri) |
endringerSiden | Dato | Henter kun prosjekter med dato_sist_endret >= oppgitt dato (f.eks. 2014-04-01). (valgfri) |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default). |
Eksempler:
- http://www.cristin.no/ws/hentProsjekter?id=301418
- http://www.cristin.no/ws/hentProsjekter?instnr=185
Tjeneste 10: hentArbeiderForProsjekt
OBS! Denne tjenesten er laget for at Forskningsrådet skal kunne hente ut de opplysningene de trenger for rapportering på prosjekter finansiert av Forskningsrådet.
Beskrivelse:
Returnerer publikasjonene (vitenskapelige arbeid) som er knyttet til et prosjekt.
Basis-URL: /ws/hentArbeiderForProsjekt
Parameterliste:
Parameter | Type | Forklaring |
---|---|---|
kilde | Streng | Hva er prosjektets finanskilde? F.eks. NFR, EU. Minst en av prosjektlopenr, arbeidlopenr, eller kilde må oppgis. |
prosjektnr | Streng | Finansieringskildens prosjektId. |
fra | Heltall | Inkluder kun arbeider med årstall >= fra |
til | Heltall | Inkluder kun arbeider med årstall <= til |
kategori | Streng | Ta med treff fra denne hovedkategorien (valgfri). Du kan angi dette parameteret flere ganger. Se Tabell 1: Hovedkategorier per 2011 og Tabell 2: Underkategorier per 2011 |
sortering | Streng | Prioritert sorteringsrekkefølge, spesifisert med en av disse strengene: HOVEDKAT_UNDERKAT_AAR. (Kategori i alfabetisk rekkefølge, mens det er nyeeste år først). |
format | Streng | Angir hva slags format man ønsker å få levert svaret på. Mulige verdier er “xml” og “json”. (valgfri, “xml” er default) |
Eksempler:
- http://www.cristin.no/ws/hentArbeiderForProsjekt?kilde=NFR
- http://www.cristin.no/ws/hentArbeiderForProsjekt?kilde=NFR&fra=2010&til=2011
- http://www.cristin.no/ws/hentArbeiderForProsjekt?kilde=NFR&prosjektnr=185143
- http://www.cristin.no/ws/hentArbeiderForProsjekt?kilde=NFR&prosjektnr=185143&kategori=DRGRADAVH&kategori=ARTIKKEL
- http://www.cristin.no/ws/hentArbeiderForProsjekt?kilde=NFR&prosjektnr=185143&kategori=DRGRADAVH&kategori=ARTIKKEL&sortering=HOVEDKAT_UNDERKAT_AAR
- http://www.cristin.no/ws/hentArbeiderForProsjekt?kilde=NFR&prosjektnr=185143&sortering=HOVEDKAT_UNDERKAT_AAR