Teknisk dokumentasjon av Cristin Web service

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.

Håndtering av feilsituasjoner
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:


 

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:


 

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:


 

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:

 

Tabell 1. Hovedkategorier per 2011
Hovedkategori Forklaring
FOREDRAG Konferansebidrag og faglig presentasjon
KOMMERSIALISERIN Kommersialisering
BOK Bok
RAPPORT Rapport/avhandling
BOKRAPPORTDEL Del av bok/rapport
MEDIEBIDRAG Mediebidrag
PRODUKT Produkt
UTSTILLING Kunstnerisk og museal presentasjon
TIDSSKRIFTPUBL Tidsskriftspublikasjon
OVERSETTELSESARB Oversettelsesarbeide
KUNST_PRODUKSJON Kunstnerisk produksjon
INFORMASJONSMATR Informasjonsmateriale

 

Tabell 2. Underkategorier per 2011
Underkategori Forklaring
ANNEN_PRESENTASJ Annet
ANNET Annet
ANNET_PRODUKT Annet produkt
ANTOLOGI Vitenskapelig antologi/Konferanseserie
ARKITEKTTEGNING Arkitekttegning
ARTIKKEL Vitenskapelig artikkel
ARTIKKEL_FAG Fagartikkel
ARTIKKEL_POP Populærvitenskapelig artikkel
BEDRIFTSETABL Bedriftsetablering
BILLEDMATERIALE Billedmateriale
BOKANMELDELSE Anmeldelse
BREV_TIL_RED Brev til redaktøren
BRIEFS Briefs
BROSJYRE Brosjyre
DATABASE Database
DIGITALE_LÆREM Digitale læremidler
DOKUMENTAR Dokumentar
DRGRADAVH Doktorgradsavhandling
ERRATA Errata
FAGBOK Fagbok
FILMPRODUKSJON Filmproduksjon
FORORD Forord
FORSKERLINJEOPPG Forskerlinjeoppgave
GJESTEFOREL Gjesteforelesning
HOVEDFAGSOPPGAVE Hovedfagsoppgave
INNLEDNING Innledning
INTERVJU Intervju
KAPITTEL Vitenskapelig Kapittel/Artikkel
KOMMENTARUTG Vitenskapelig kommentarutgave
KOMPENDIUM Kompendium
KRONIKK Kronikk
KUNST_OG_BILDE Kunst- og billedmateriale
LEDER Leder
LEKSIKAL_INNF Leksikalsk innførsel
LEKSIKON Leksikon
LESERINNLEGG Leserinnlegg
LISENS Lisens
LISENSIATAVH Lisensiatavhandling
LYDMATERIALE Lydmateriale
LÆREBOK Lærebok
MAGISTERAVH Magisteravhandling
MASTERGRADSOPPG Mastergradsoppgave
MODELL_ARKITEKT Modell (arkitektur)
MONOGRAFI Vitenskapelig monografi
MULTIMEDIAPROD Multimediaprodukt
MUSEUM Museumsutstilling
MUSIKKARR Musikkarrangement
MUSIKK_DELKOMP Musikk - delkomposisjon
MUSIKK_FRAMFORIN Musikalsk framføring
MUSIKK_INNSP Musikk - innspillingsprodukt
MUSIKK_KOMP Musikk - komposisjon
NETTSIDER Nettsider (opplysningsmateriale)
OPPSLAGSVERK Oppslagsverk
OVERSETTELSE Oversettelse
OVERSETTELSE_BOK Bok
OVERSETTELSE_KAP Kapittel/Artikkel
OVERSIKTSART Vitenskapelig oversiktsartikkel/review
PATENT Patent
POPVIT_BOK Populærvitenskapelig bok
POPVIT_FOREDRAG Populærvitenskapelig foredrag
POSTER Poster
PROGDELTAGELSE Programdeltagelse
PROGINNL Innledning i musikal og teaterprogram
PROGLEDELSE Programledelse
PROGRAMVARE Programvare
RAPPORT Rapport
SAMMENDRAG Sammendrag/abstract
SEMINAR Seminar
SHORTCOMM Short communication
TEATERPRODUKSJON Teaterproduksjon
UTST_ARKITEKT Arkitektutstilling
UTSTILLINGSKAT Utstillingskatalog
UTST_KUNST Kunstutstilling
UTST_WEB Webutstilling
VIT_FOREDRAG Vitenskapelig foredrag

 

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:

 

Tabell 3. Presentasjonstyper
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:


 

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

 

Publisert 23. aug. 2017 15:04 - Sist endret 19. okt. 2017 09:39