Beskrivning av subsystemet och tjänsterna i API-katalogen

Du måste vara inloggad i API-katalogen och ha rätt att redigera din organisations uppgifter i API-katalogen.

Den som är administratör i din organisation ger dig behörighet att redigera uppgifterna. Anvisningar för användaradministrationen för API-katalogen finns i Suomi.fi-serviceadministrationens stödartikel. 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.

För att ändra uppgifterna om ditt subsystem, gå till uppgifterna i API-katalogen och välj Hantera.

Subsystemets namn förs automatiskt från Informationsleden, men du kan ändra namnet i API-katalogen. Vi rekommenderar att du byter namnet så att det beskriver subsystemets tjänster allmänbegripligt.

Beskrivningen av subsystemet anger vilka tjänster och uppgifter subsystemet tillhandahåller och hur tjänsterna kan tas i bruk. Beskrivningen av subsystemet är ett servicelöfte som marknadsför dess tjänster, dvs. gränssnitt och innehållsuppgifter.

Om subsystemet endast utnyttjar andra tjänster i Informationsleden, använd följande mening: "Subsystemet erbjuder inte tjänster, utan utnyttjar endast information som fås via Suomi.fi-informationsleden."

Vi rekommenderar att subsystem ska vara tjänstespecifika. Om det emellertid finns flera tjänster i samma subsystem, kan du beskriva en enskild tjänst närmare i tjänstens egen beskrivning.

Ange följande uppgifter om subsystemet:

Subsystemets namn

Subsystemets beskrivning

• Subsystemets allmän beskrivning: Vilken typ av tjänster erbjuder subsystemet och på vilka språk? Vilka är fördelarna att använda tjänsterna? Berätta i beskrivningen hur andra organisationer kan ha nytta av tjänsten. På så sätt får andra organisationer en överblick över tjänsten och kan bedöma om det lönar sig för deras organisation att börja använda den. Hur kan man få mer information om tjänster?
• Villkor och begränsningar vid användningen av tjänster: Vilka organisationer kan ta i bruk tjänster? Kräver ibruktagning av tjänster separata tillståndsansökningar? Beskriv tillståndsprocessen.
• Ibruktagning av tjänster: Hur kan man ta i bruk tjänster? Beskriv processen för ibruktagandet kort på ett allmänt plan. Hur kan man få mer information om ibruktagningen av tjänster?

Ämnesord

• Ge subsystemet ämnesord som beskriver de tjänster som tillhandahålls av systemet eller som är väsentligt förknippade med det. Till exempel har VTJ-gränssnittssystemet fått ämnesorden "befolkningsdatasystemet", "personbeteckning", "personuppgifter" osv.
• I API-katalogen kan man förutom namn och textfält även söka med ämnesord. Ett subsystem och med relaterade tjänster hittas enklare i API-katalogen när de försetts med lämpliga ämnesord. När du ger ett subsystem olika ämnesord, tänk på vilka sökord du själv skulle använda för att söka tjänsterna i fråga.
• Du kan söka efter lämpliga ämnesord i ontologier eller andra ämnesordregister inom din organisations fackområde. Till exempel den finländska tesaurus- och ontologiservicen FintoÖppnas i ett nytt fönster. underhåller den allmänna finländska ontologin ALLFOÖppnas i ett nytt fönster..

Administratörens kontaktuppgifter

• Ange kontaktuppgifterna till administratören av subsystemet så att intresserade organisationer kan be om mer information om de tjänsterna som ingår i det.
• 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 tjänsterna att tas upp till behandling även om en person som vanligtvis handlägger dem skulle vara frånvarande.

Synlighet

• Du kan publicera ett subsystem i API-katalogen så att det kan ses av alla som bläddrar i katalogen genom att överföra den till statusen Offentlig. Om subsystemet har statusen Privat kan bara medlemmarna i den organisation som administrerar subsystemet se det i API-katalogen.
• Du kan använda statusen Privat till exempel om beskrivningen av ett subsystem inte ännu är klar och du därför inte vill att subsystemet ska visas offentligt i katalogen.

Giltighetstid

• I punkten Giltig sedan ska du ange från och med vilket datum subsystemets tjänsten eller tjänsterna är tillgängliga. Om tjänsten gäller tills vidare kan du lämna punkten Giltig till tom. Om du däremot känner till det datum då tjänsten ska ändras eller tas bort från Informationsleden, meddela detta under Giltig till.

Tänk också på följande när du sammanställer en beskrivning:

• Du bör 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 Myndigheten för digitalisering och befolkningsdatas beskrivning av VTJ-gränssnittetÖppnas i ett nytt fönster..
• Använd formatering. Det blir lättare att förstå texten när du använder formatering. Det löns att dela in beskrivningen med hjälp av underrubriker i tre delar som visas ovan: Subsystemets allmän beskrivning, Villkor och begränsningar vid användningen av tjänster och Ibruktagning av tjänster. Du kan framhäva de viktigaste punkterna i texten till exempel med fet stil.
• Skriv beskrivningen även på finska och engelska. Språkversionerna ska ifyllas i egna fält och de visas om användaren använder API-katalogen på ett annat språk. Glöm inte bort språkversionerna när du gör uppdateringar i beskrivningen.

För att ändra uppgifter av en enskild tjänst i API-katalogen, gå till uppgifterna i det subsystemet via vilket tjänsten importeras till Informationsleden. Under rubriken Tjänster väljer du den tjänsten du vill ändra. Välj därefter Hantera.

Bild: Bild 1. Beskrivningar av enskilda tjänster (gränssnitt) som tjänsten Fullmakter tillhandahåller i API-katalogen.

Visa större bilden

Redigera en enskilda tjänstens uppgifter om. Man kan redigera följande uppgifter:

• Tjänstebeskrivning: Lägg till en kort allmän beskrivning av tjänsten så att användare som vill utnyttja din tjänst (gränssnitt) förstår tjänstens funktion bättre.
• Tjänstens synlighet
• Tjänstens avgifter
• Giltighetstid
• Filformat

Tjänsterna är synliga i API-katalogen när de har lagts till på anslutningsserver. Om din tjänst inte visas i API-katalogen, kontrollera att den har lagts till på anslutningsservern enligt instruktionerna. Om tjänsten visas som okänd i API-katalogen, se instruktioner för teknisk beskrivning av tjänsten i API-katalogen. Vid behov kontakta Informationsledens administratör: palveluvayla@palveluvayla.fi.

Varje tjänst ska ha en teknisk beskrivning som publiceras i API-katalogen som en WSDL- eller OpenAPI-fil som kan läsas automatiskt från Informationsleden. Dessutom kan du ladda ner andra bilagor i API-katalogen, såsom PDF-filer, där du kan beskriva till exempel tjänstens användarvillkor närmare.

Dokumentera tjänster som följer REST-arkitekturen i enlighet med OpenAPI-specifikationen. API-katalogen har en förhandsvisning av OpenAPI-beskrivningarna, varvid den som bläddrar i katalogen snabbt får de viktigaste uppgifterna om din tjänst. Om du inkluderar länkar i beskrivningen ska du se till att de fungerar och inte är till exempel interna länkar. Läs mer om OpenAPI-dokumentation:

• OpenAPI specification (GitHub, på engelska)Öppnas i ett nytt fönster.
• OpenAPI basic structure (på engelska)Öppnas i ett nytt fönster.

Mer information finns i en annan artikel.

Kontakta Informationsledens support på palveluvayla@palveluvayla.fi om dessa anvisningar inte var till hjälp i din situation.