Guide för administratör
Komplettering av uppgifter i API-katalogen
Innehåll
1 API-katalogens anslutningsbeskrivningar är väsentliga för användningen av Informationsleden
2 Uppgifter om organisationen och användaren
4 Beskrivningen i filbilagan ger vägledning i det tekniska ibruktagandet av ett enskilt gränssnitt
5 Datamodell och begrepp i API-katalogen
1 API-katalogens anslutningsbeskrivningar är viktiga för användningen av Informationsleden
Anslutningsbeskrivningarna är väsentliga med tanke på användbarheten hos API-katalogen och hela Informationsleden, eftersom de visar den som bläddrar i katalogen hurdana anslutningar som är tillgängliga via Informationsleden.
Uppgifter som beskriver anslutningarna (s.k. metadata) bör administratörerna i organisationerna själva införa i API-katalogens gränssnitt. Allmänna beskrivningar av anslutningarna och administratörens kontaktuppgifter är exempel på metadata av det här slaget.
Uppgifter om anslutningarnas gränssnitt, som till exempel namn och gränssnittsbeskrivningar, uppdateras dagligen automatiskt från Informationsleden till API-katalogen.
2 Uppgifter om organisationen och användaren
Hur kan man redigera uppgifter om organisationen i API-katalogen?
Om du vill ändra uppgifterna om din organisation, gå till uppgifterna i API-katalogen och klicka på knappen Hantera. Du måste vara inloggad i API-katalogen och ha rätt att redigera organisationens uppgifter i katalogen.
Den som är administratör av API-katalogen i din organisation ger dig behörighet att redigera uppgifterna. Om ingen i din organisation är behörig att redigera organisationens uppgifter, be om rättigheter och användarkoder av oss som underhåller API-katalogen: palveluvayla@palveluvayla.fi
Vilka uppgifter ska organisationsbeskrivningen innehålla?
I beskrivningen anger du kort, allmän information om din organisation: vad organisationen är och vad den gör. Du kan nämna med några meningar hurdana anslutningar och hurdan information organisationen tillhandahåller via Informationsleden. En länk till organisationens webbplats kan skapas till beskrivningen.
Exempelvis innehåller organisationsbeskrivning av Myndigheten för digitalisering och befolkningsdata basuppgifterna om organisationen. Den har också länkar till webbplatsen dvv.fi.
Logotyp/Bild
Det är bra att även införa organisationens logotyp i API-katalogen. Du kan ladda upp organisationens logotyp från din arbetsstation genom att klicka på knappen Ladda upp.
Användarmedlemmar
Myndigheten för digitalisering och befolkningsdata lägger till den första användaren och därefter kan organisationen själv administrera användarna och deras behörigheter samt kalla in nya användare. Vid behov kan du begära administratörskoder av oss som underhåller API-katalogen. palveluvayla@palveluvayla.fi
API-katalogen har olika användarroller som har olika rättigheter:
- Admin: Lägga till, redigera och ta bort en anslutning. Administrera organisationens medlemmar.
- Redaktör Läsa om anslutningar, lägga till en anslutning och redigera en anslutning.
- Medlem: Läsa om anslutningar.
Obligatoriska uppgifter om användarna är: användarnamn, lösenord, status och roll. En användare kan också ges en beskrivning och ett namn, men sådana uppgifter är frivilliga.
3 Uppgifterna i anslutningsbeskrivningen anger vad anslutningen har att erbjuda och hur man kan ta i bruk den
Hur kan man redigera uppgifter om anslutningar i API-katalogen?
Om du vill ändra uppgifterna om din anslutning, gå till uppgifterna i API-katalogen och klicka på på knappen Hantera. Du måste vara inloggad i API-katalogen och ha rätt att redigera organisationens uppgifter i katalogen.
Den som är administratör i din organisation ger dig behörighet att redigera uppgifterna. Om ingen i din organisation är behörig att redigera organisationens uppgifter, be om rättigheter och användarkoder av oss som underhåller API-katalogen: palveluvayla@palveluvayla.fi
Tänk på att du inte kan ändra namnet på en anslutning i API-katalogen eftersom det kommer automatiskt från Informationsleden.
Vilka uppgifter ska anslutningsbeskrivningen innehålla?
Beskrivningen av en anslutning är ett servicelöfte som marknadsför anslutningens gränssnitt och informerande innehåll. Du bör alltså inte skriva alltför tekniskt, utan sträva efter allmänbegripliga uttryck. Skriv kort och koncist men kom ihåg allt som är väsentligt. Se till exempel beskrivning av BDS-gränssnittstjänsten (på finska).
Ange följande i beskrivningen:
- Hurdana uppgifter man kan få tillgång till via anslutningen
Berätta i beskrivningen hur andra organisationer kan ha nytta av anslutningen. På det sättet får andra organisationer en allmän bild av anslutningen och kan bedöma om det lönar sig för dem att börja använda den. - Vilka begränsningar som gäller användningen av anslutningen
Berätta i beskrivningen vilka begräsningar som gäller användningen av anslutningen. Specificera till exempel vem som kan ta i bruk anslutningen. Berätta också om andra eventuella begränsningar till exempel gällande tiderna när anslutningen kan användas, praxis om datatillstånd, avgifter och offentligheten hos informerande innehåll. - Hur man börjar använda anslutningen
Ange i beskrivningen hur andra organisationer ska göra för att få mer information om anslutningen eller ta i bruk den. Beskriv processen för ibruktagandet kort på ett allmänt plan och berätta var man får mer information. Kontaktuppgifterna till den som administrerar anslutningen meddelas i ett eget fält, men om det finns fler kontaktuppgifter kan du meddela även dem i beskrivningsfältet.
Tänk även på följande när du beskriver anslutningen:
- Använd formatering
Det blir lättare att förstå texten när du använder formatering. Det är bra att dela in beskrivningen med hjälp av underrubriker (till exempel i tre avsnitt som ovan: Vad / På vilka villkor / Hur). Du kan framhäva de viktigaste punkterna i texten till exempel med fet stil.
Obs! Formateringar i texten fås som s.k. Markdown-formatering. Klicka på Här kan du använda Markdown-formateringar nedanför beskrivningsfältet för att se formateringsmöjligheterna. Rubrikformatering får du till exempel genom att lägga till #-tecknet framför rubriken. Skriv till exempel så här i beskrivningsfältet: ”# Förutsättningar för att använda uppgifterna” så får du en mellanrubrik som i exemplet intill. Läs mer om Markdown-formatering på webbsidan Markdown Guide (på engelska). - Skriv beskrivningen även på finska och engelska
Språkversionerna ska ifyllas i egna fält (under den första beskrivningen) och de visas om användaren använder API-katalogen på ett annat språk. Glömt inte bort språkversionerna när du gör uppdateringar i beskrivningen.
Taggar
Ange taggar/ämnesord för som beskriver hurdan information anslutningen tillhandahåller eller som har nära samband med anslutningen. Exempelvis har ”befolkningsdatasystemet”, ”personbeteckning”, ”personuppgifter” osv. angetts som taggar för BDS-gränssnittsanslutningen.
I API-katalogen kan man förutom namn och textfält även söka med ämnesord. En anslutning som har försetts med bra ämnesord är alltså lättare att hitta i API-katalogen. När du ger en anslutning lösenord, tänk på vilka sökord du själv skulle använda för att söka ifrågavarande gränssnittstjänst.
Träder i kraft (Giltighetstid)
I punkten Träder i kraft anger du från och med när anslutningen är i bruk.
Om anslutningen gäller tills vidare kan du lämna punkten Går ut tom.
Om du däremot känner till när anslutningen kommer att ändras eller tas bort från Informationsleden, ange datumet i punkten Går ut.
Miljö
Punkten Miljö hänvisar till olika miljöer i Informationsleden. Med hjälp av den kan man alltså hålla isär anslutningarna i test- och produktionsmiljön. Eftersom testmiljön inte används för närvarande behöver punkten inte fyllas i.
Synlighet
Du kan publicera en anslutning i Informationsledens API-katalog så att alla som bläddra i katalogen genom att överföra den till statusen Offentlig. Om anslutningen har statusen Privat kan bara den organisation som administrerar anslutningen se den i API-katalogen.
Du kan använda statusen Privat till exempel om beskrivningarna av en anslutning inte ännu är klara och du därför inte vill att anslutningen ska visas offentligt i katalogen.
Delad resurs
Välj alltid Ja om andra organisationer kan dra nytta av anslutningen.
Anslutningens kontaktuppgifter
Ange kontaktuppgifterna till anslutningens administratör för att organisationer som är intresserade av anslutningen ska kunna begära mer information om den.
Ange organisationens sektorbestämda e-postadress i stället för en personlig adress, om det är möjligt. På det sättet kommer förfrågningar om anslutningen att tas upp till behandling även om en person som vanligtvis handlägger dem skulle vara frånvarande.
4 Filbilagor ger vägledning i det tekniska ibruktagandet och användningen av ett enskilt gränssnitt
En anslutnings filbilagesida eller -sidor består av ett sammandrag och en automatiskt skapad förhandsvisning av innehållet i den egentliga anslutningsfilen. Dessutom kan man för en filbilaga ange andra uppgifter, till exempel en beskrivning av filbilagan. Skapa en egen bilagesida för varje gränssnitt. Du kan ta exempel av BDS-gränssnittsanslutningen (på finska), som har många filbilagor.
Beskrivningen av anslutningens filbilaga syftar till att utgöra en teknisk anvisning för ibruktagandet och användningen av ett enskilt gränssnitt. Här ska du alltså beskriva hur man kan ta i bruk gränssnittet och vad allt man bör tänka på när man använder det.
Följande uppgifter kan ges en filbilaga:
- Beskrivning FI, SV, EN
- Typ FI, SV, EN
- Avgiftsbelagd Ja/Nej/Se beskrivningen
- Filformat
- Giltighetstiden börjar
- Giltighetstiden slutar
- Anslutningsuppgifter FI, SV, EN
- Tillgänglighet FI, SV, EN
- Service Level Agreement FI, SV, EN
- Genomsnittlig svarstid
- Tjänstens status FI, SV, EN
- Licens
5 Datamodell och begrepp i API-katalogen
I API-katalogen har vi samlat alla anslutningar, dvs. gränssnittstjänster, som tillhandahålls via Suomi.fi-informationsleden samt deras administratörer. Med hjälp av API-katalogen kan organisationer som planerar att ta i bruk Informationsledens gränssnittstjänster se vilka anslutningar och uppgifter som står till buds i Informationsleden. En anslutning som beskrivits i katalogen kan tas i bruk genom ett avtal med den som administrerar anslutningen.
API-katalogen innehåller alltid aktuella uppgifter om de organisationer som anslutit sig till Informationsleden och deras anslutningar. De senaste uppgifterna om anslutningarna sållas varje natt till API-katalogen. Informationsledens centralserver plockar upp dem från kundspecifika anslutningsservrar.
Utöver de uppgifter som kommer automatiskt från Informationsleden ska organisationerna själva i kataloggränssnittet beskriva organisationen, användarna, anslutningen och filbilagorna (metadata).
- En organisation är en organisation som använder Informationsleden.
- En användare är en medlem av användarorganisationen eller till exempel en teknisk operatör som har rätt att agera i användarorganisationens ställe.
- Anslutning: En gränssnittstjänst som kan omfatta ett eller flera gränssnitt.
Exempel: I BDS-anslutningen (på finska) har basuppgifterna beskrivits på en sida och därtill finns en lista på filbilagor, av vilka minst en är en WSDL-fil som plockas ut automatiskt från Informationsledens centralserver. - Gränssnitt: Hör bara samman med en tjänst och innehåller alltid bara en teknisk beskrivning som visas visuellt i API-katalogen (t.ex. WSDL eller XML-beskrivning).
Exempel: Till BSD-anslutningen hör flera gränssnitt, av vilka en del är instruerande, som exempelmeddelanden. Se till exempel BDS-anslutningens gränssnitt ”HenkilönTunnuskysely” (Sökning med personbeteckning). - Filbilaga (Data och gränssnitt): En anslutning har alltid minst en filbilaga: en WSDL-beskrivning som sållas ut automatiskt från Informationsledens centralserver. Utöver denna obligatoriska bilaga kan det finnas andra, till exempel anvisningar om eller exempel på förfrågnings- och svarsmeddelanden.