SIL HTTP API

SIL HTTP API

SIL erbjuder ett HTTP-baserat API för åtkomst till information om läkemedelssubstanser. Vi avser att på sikt erbjuda HTTP-baserade API:er för åtkomst till annan läkemedelsinformation, som tex. den som finns åtkomlig via SIL SOAP API idag.

Syftet med att erbjuda ett HTTP-baserat API är att förenkla åtkomst till och användning av SIL:s informationstjänster samt erbjuda ett tekniskt integrationsalternativ som är ändamålsenligt anpassat till de tekniskt heterogena och organisatoriskt oberoende miljöer som finns inom sjukvården och på Internet.

Vi har strävat efter att göra SIL HTTP APIREST-fullt som möjligt! Med det menar vi att vi försökt uppfylla de arkitektur- och designprinciper och avgränsningar som går under samlingsnamnet REST (Representational State Transfer) och som varit grundläggande för HTTP protokollet och WWW. REST formulerades ursprungligen 2000 av Roy Fielding i hans doktorsavhandling Architectural Styles and the Design of Network-based Software Architectures.

Specifikt baseras SIL HTTP API på följande principer:

  •  Information tillgängligörs i form av resurser, som representerar olika begrepp rörande läkemedelsinformation.
  •  Dessa resurser är unikt identifierade genom URL:ar.
  •  Resurser kan ha olika representationer eller mediatyper som tex JSON, XHTML eller PDF.
  •  Resurserna kan manipuleras genom användning av HTTP metoder. Då SIL HTTP API är ett read-only API är de relevanta tjänsterna GET, OPTIONS och HEAD.
  •  Klienter kan navigera i tjänsterna och mellan resurser genom att följa hyperlänkar (HATEOAS).

SIL HTTP tjänster kan delas upp i tre sorters tjänster:

  • Navigeringstjänster. Detta är utformade för att klienter ska kunna navigera bland olika resurser.
  • Söktjänster. Dessa är för klienter ska kunna söka efter resurser baserat på diverse sökkriterier.
  • Integrationstjänster. Dessa tjänster är av mera teknisk natur och kan användas för att underlätta den tekniska integrationen för klienter.

Nyttjandeavtal

SIL HTTP API ägs och tillhandahålls av Inera AB. Kontakta SIL för information om nyttjandevillkor. Idag finns inga krav på automatisk registrering eller några avgifter för nyttjande av SIL HTTP tjänster.

Data som returneras i SIL HTTP substanstjänster kommer från NPL (Läkemedelsverket) och är att betrakta som offentlig information.

Applikationsnycklar

I dagsläget krävs inte applikationsnycklar för att använda SILL HTTP API:er. På sikt kan applikationsnycklar införas för åtkomst till SIL HTTP API:er i syfte att säkerställa att enbart registrerade klienter kommer åt tjänsterna och för att följa upp användning av tjänsterna.

SIL HTTP Substanstjänster

SIL HTTP substanstjänster ger åtkomst till information om läkemedelssubstanser. All information om läkemedelssubstanser i dessa tjänster hämtas idag från NPL (Nationellt Produktregister för Läkemedel, Läkemedelsverket). När Läkemedelsverket är klara med NSL (Nationellt Substansregister för Läkemedel) kommer det att användas som grundkälla för SIL HTTP substanstjänster.

Informationen om läkemedelssubstanser i NPL har inte formellt status som ett kvalitetssäkrat eller nationellt substansregister.

Uppdateringsfrekvens

Datainnehållet i SIL HTTP Substanstjänster uppdateras synkroniserat med publiceringen av SIL databas varje vecka (på torsdag eftermiddag).

Bas-URL

Adressen till SIL HTTP substanstjänster är:

  http://substances.silinfo.se

Via denna URL kan alla tjänster och resurser nås i SIL HTTP substanstjänster.

I dokumentationen nedan avser symbolen <Base> ovanstående URL och den används som bas-URL för åtkomst till alla resurser i substanstjänsterna. Det är viktigt att integratörer undviker att hårdkoda URL:ar och speciellt då bas-URL:en i anropande program. I möjligaste mån ska URL:ar vara konfigurerbara eller hämtas via navigering från från bas-URL:en.

URL-mallar

Här är en förteckning över URL-mallar (på engelska: URL templates) till resurser i SIL HTTP substanstjänster. Allt som står inom klammerparanteser ‘{’ och ‘}’ ska ersättas med strängvärden vid anrop.

ResursnamnURLHTTP-
metod
ResponsTillgängligt
Navigationsresurser    
API<Base>GETBasresurs och ingång till API:et. Innehålller dokumentation om API:et och länkar och URL-mallar till alla tjänster.2012-03-29
terminologies<Base>/terminologies
<Base>/terminologies/?lang={language}
GETOm ingen query-parameter anges returneras en lista med alla giltiga substansterminologier. Med query-parametern kan man avgränsa listan till att enbart innehålla substansterminologier i det angivna språket.2012-03-29
terminology<Base>/terminologies/{terminology}GETInformation om den angivna terminologin {terminology}2012-03-29
substance<Base>/substances/{terminology}/{name}GETInformation om substansen {name} i den angivna terminologin {terminology}.2012-03-29
substances_in_terminology<Base>/substances/{terminology}GETEn lista med alla substansnamn i den angivna terminologin {terminology}.2012-03-29
groups<Base>/substances/{terminology}/{name}/groupsGETEn lista med alla substansgrupper som inkluderar substansen {name} i den angivna terminologin {terminology}. 
included<Base>/substances/{terminology}/{name}/includedGETOm substansnamnet {name} i den angivna terminologin {terminology} avser en substansgrupp, returneras alla substanser som ingår i den substansgruppen. 
synonyms<Base>/substances/{terminology}/{name}/synonymsGETEn lista med synonyma termer till substansen {name} i den angivna terminologin {terminology}.2012-03-29
products<Base>{terminology}/{name}/productsGETEn lista med alla läkemedelsprodukter i vilken substansen {name} i den angivna terminologin {terminology} är en aktiv substans.2012-03-29
interagents<Base>/terminologies/{terminology}/sid/{name}/interagentsGETEn lista med substanser som har kända interaktioner med substansen {name} i den angivna terminologin {terminology}.Senare
Sökresurser    
substance_name_prefix<Base>/query/prefix/{prefix} GETEn lista med alla substansnamn som börjar med prefixet {prefix}.2012-03-29
substance_name_match<Base>/match?q={pattern}GETEn lista med alla substansnamn vars namn matchar {pattern}. Möjliga specialtecken för sökning i {pattern} är jokertecknen (på engelska: wildcards) ‘?’ (matchar exakt ett tecken) och * (matchar 0 eller flera tecken) samt teckenmängdssyntaxen [abc] (för tecken som ska matchas) och [~abc] (för tecken som inte ska matchas).2012-03-29
suggestions<Base>/suggestions/{term}GETEn lista med alla substansnamn som liknar den angivna termen {term} baserat på lexikal likhet. Tex. "diclofenac" och "diklofenak".Senare
search<Base>/search?q={query_text} GETEn lista med alla substanser som innehåller text någonstans i sin informationsmängd som matchar {query_text}.Senare
OpenSearch-resurser    
OS-Descripion Document<Base>/osGETOpen search integrationsresurs.Senare
OS-Query<Base>/os?q={search_terms}GETOpen search sökresurs.Senare
OS-Suggestions<Base>/os/suggest?{search_terms} Open search förslagsresurs.Senare

Resurser

I SIL HTTP substanstjänster finns information om substansnamn. Det finns också information om substansgrupper som är namngivna grupper av substanser. Dessa grupper kan baseras på gemensamma kemiska, terapeutiska eller andra egenskaper som de ingående substanserna delar. Substansnamn och substansgrupper hör till olika terminologier. Exempel på terminologier är "NPL-substansid", "NPL WHO INN" och "ATC".

Man kan få information om synonymnamn på substanser. Synonymhanteringen i SIL HTTP substanstjänster baseras enbart på information i NPL läkemedelsprodukt-, substans- och ATC-kodsregister. Man kan också få information om läkemedelsprodukter.

Resurs: Terminologi 

AttributBeskrivningExempel
langISO språkod för språket i terminologin. Om språkkoden är "all"innebär det att terminologin är språkneutralt.en, sv, all.
descTextbeskrivningINN = International Non-propietary Name (WHO)
substancesLänk till alla substansnamn i termonologin./substances/CASNO

Resurs: Substans

AttributBeskrivningExempel
groupsSubstansgrupper som denna substans ingår i.ATC
idUnikt id för substansen.n06bx12 [ATC]
includedIngående substanser, om denna substans är en substansgrupp 
productsLäkemedelsprodukter som denna substans ingår i (aktiv eller som aktiv respondent). 
synonymsAndra namn på denna substans organiserade per terminologi.ATCSV: acetylcarnitin

Resurs: Läkemedelsprodukt

Resursen Läkemedelsprodukt innehåller i dag en del data från NPL. Dessutom finns i varje läkemedelsprodukt en länk (attributet ‘_::lvlink’) till informationssidan på Läkemedelsverkets webbsajt där mer textuell information om den produkten finns. Där kan bla. produktens SPC (produktresumé) hämtas.

Denna resurs kommer att genomgå en översyn i samband med utveckling av SIL HTTP tjänster för läkemedelsprodukter.

Representationsformat

Resurser som returneras av SIL HTTP substanstjänster kan representeras med följande mediatyper: application/x-python, application/json och application/xhtml+xml. Om inget specifikt anges av klienter via HTTP-headern Accept så returnerar tjänsterna application/xhtml+xml så att de kan enkelt presenteras i vanliga webbläsare.

Exempel

För att hämta information om alla terminologier kör

  HTTP GET /terminologies

För att söka efter substansnamn som innehåller strängen "cetyl" kör

  HTTP GET /query/match?q=*cetyl*