Konto
För att du ska kunna logga in i WSO2 API Manager krävs det att du har ett konto och är registrerad som “Publisher”. Skicka ett mail till Per Persson (per.z.persson@sundsvall.se) så skapar vi ett konto till dig.
Riktlinjer och regler
Innan du börjar publicera API:er så ska du ha koll på de riktlinjer och regler vi har kring livcykelhantering av API:er. Detta går att läsa på denna sida: Regler och riktlinjer
Under Livscykelhantering av APIer beskrivs vilka versioner av API:er som ska publiceras i vilken gateway och på vilken endpoint m.m.
Skapa API
Här beskrivs hur du går tillväga för att skapa ett API i WSO2 API Manager.
Skapa ett API utifrån en OpenAPI-specifikation (swagger)
Surfa in på webbadressen till WSO2 API Manager Publisher, denna adress slutar på: /publisher/apis
Logga in med dina användaruppgifter.
Klicka på “CREATE API” och välj “I Have an Existing REST API”.
Välj att antingen bifoga en länk till din OpenAPI-specifikation eller välj att ladda upp den direkt från din dator.
I fältet “Name” anger du ett namn på ditt API. Detta namn kommer endast synas i API Managern. Välj därför ett namn som är tydligt för de som ska konsumera ditt API. Versal som första bokstav.
I fältet “Context” anger du starten på sökvägen till ditt API. Detta är oftast samma som namnet på API:t men här ska det endast förekomma gemener. Eventuella mellanrum skrivs med bindestreck (example-with-spaces).
I fältet “Version” anger du versionen på ditt API. Denna version inkluderas i sökvägen till ditt API.
I fältet “Endpoint” anger du sökvägen till ditt bakomliggande API.
I fältet “Business plan(s)” anger du om du vill ha någon begränsning på antal anrop till ditt API.
Nu har du skapat ett API. För att klienter ska kunna anropa ditt API så måste du publicera det. Men först ska vi gå igenom några delar som är bra att känna till innan vi gör det.
Exponera internt och/eller externt
Tänk på skillnaden mellan olika endpoints och vilken API Gateway de exponeras i. Detta beskrivs här: https://sundsvall.atlassian.net/wiki/spaces/SK/pages/344588314/Livscykelhantering+av+APIer#Hur-konfigurerar-vi-APIer-i-API-Manager%3F
APIer som skall anropas av interna klienter (klienter på kommunens nät) skall nås via api-i.sundsvall.se (intern gateway)
APIer som skall anropas av klienter på vårt DMZ eller på Internet skall nås via api.sundsvall.se (extern gateway)
Om ett API har både interna och externa klienter skall det alltså vara nåbart både via api-i.sundsvall.se och api.sundsvall.se
Konfigurering
När du är inne på ditt API i API Manager Publisher så finns fliken “Enivronments” till vänster. Klicka på den.
Här kan du välja hur API:t ska exponeras.
Valet “Production and Sandbox” innebär att API:t exponeras i vår interna gateway och endast går att nå internt på Sundsvalls kommuns nät.
Valet “External Production and Sandbox” innebär att API:t exponeras externt och går att nå utanför Sundsvalls kommuns nät
Klicka på “Save” för att spara ändringen.
Autentisering
När du är inne på ditt API i API Manager Publisher så finns fliken “Runtime Configurations” till vänster. Klicka på den.
Här kan du se “Application Level Security”. Klicka på texten så expanderas fältet.
Här kan du välja vilken typ av säkerhet som ska användas på ditt API.
Standard-inställningen är “Oauth2” och denna säkerhet används för icke öppna API:er (informationssäkerhetsnivå > 0). Detta är en säkerhetstyp med en tidsbegränsad accessnyckel.
Ett annat alternativ för öppna API:er (informationssäkerhetsnivå = 0) är att använda säkerhetstypen “Api Key”. Detta är en säkerhetstyp med en statisk accessnyckel.
Klicka i det alternativ som stämmer överens med ditt API och klicka på “Save” för att spara ändringar.
Transport level security
Under samma flik som i tidigare steg (“Runtime Configurations”) ska vi även konfigurera transportprotokoll.
Klicka på “Transport level security” och säkerställ att endast “HTTPS” är markerad.
Klicka sedan på “Save” för att spara ändringarna.
Publicera API
Nu har vi kommit fram till det sista steget. Att publicera ditt API för de som vill konsumera det.
När du är inne på ditt API i API Manager Publisher så finns fliken “Lifecycle” till vänster. Klicka på den.
För att kunna publicera ditt API så krävs det att du har uppfyllt vissa kriterier. Dessa ser du till höger:
När du har verifierat att alla kriterier är uppfyllda så klickar du på knappen “Publish”.
Nu är ditt API publicerat och redo att användas!
Skapa användare
För att konsumenterna ska få tillgång till ditt API krävs det att de är upplagda som användare i WSO2 och prenumeranter på ditt API.
Användare för en ny klient (en ny kanal t ex) skapas i Carbon av t ex Per Persson (per.z.persson@sundsvall.se).
Skapa prenumeration på API
Surfa in på WSO2 API Manager Developer Portal, denna adress slutar på: /devportal
Logga in på Developer Portal med den användare (WSO2_OpenE t ex) som skall prenumerera på APIet
Klicka på det API användaren skall prenumerera på
Klicka på knappen “Subscribe” till vänster
Klicka på Subscribe (se nedan - ändra inte under Application eller Throttling Policy)
Skapa nycklar för en prenumerant
Det finns två typer av nycklar.
“Production keys”, dessa nycklar används för att anropa API:ernas “Production endpoint”
“Sandbox keys”, dessa nycklar används för att anropa API:ernas “Sandbox endpoint”
Logga in på Developer Portal med den användare (WSO2_OpenE t ex) som skall prenumerera på APIet
När du är inne på WSO2 API Manager Developer Portal och fliken “Applications” så kan du se användarens applikation (DefaultApplication)
Välj Action “Edit” för DefaultApplication och klicka på “Save” utan att förändra någon information
Välj antingen “Production keys” eller “Sandbox keys” i flikarna till vänster beroende på vilken typ av nycklar du vill skapa.
Välj antingen “Oauth2 Tokens” eller “Api Key” beroende på vilken säkerhetstyp du valde på ditt API.
För OAuth2 Tokens:
Verifiera att alternativet “Client Credentials” är ikryssad vid rubriken “Grant Types”. Det är denna metod som klienten ska använda för att hämta access nyckel.
Klicka på “GENERATE KEYS”
Du ser nu en “Access Token”, denna behöver du inte. Så klicka på “CLOSE”.
Nu kan du se “Consumer Key” och “Consumer Secret”. Klicka på kopieringssymbolen i dessa fält och spara dessa på en säker plats. Dessa ska vi skicka till konsumenten på ett säkert sätt i nästa steg.
För API Key:
Klicka på “GENERATE KEY”
Du ser nu en genererad API Key, klicka på kopieringssymbolen till höger om fältet och spara denna på en säker plats. Denna nyckel ska vi skicka till konsumenten på ett säkert sätt i nästa steg.
Leverera nycklar på ett säkert sätt
Denna information ska förmedlas till konsumenten:
Namnet på användaren nycklarna tillhör
Typ av nyckel (Production eller Sandbox)
Säkerhetstyp (Oauth2 eller API Key)
Om säkerhetstypen är Oauth2, informera om att vi använder “Client Credentials” som “Grant Type”
Nycklarna
URL till det API som kan anropas med nycklarna
Nu måste vi leverera denna information till konsumenten som ska använda dessa. För att inte fel person ska få tag i dessa nycklar så krävs det att vi skickar dessa på ett säkert sätt. Ett enkelt sätt att skydda informationen är att skicka ett Word-dokument som är krypterat med lösenord. Här kommer en beskrivning på hur du går tillväga:
Skapa ett nytt Word-dokument
Gå på Arkiv > Info > Skydda dokument > Kryptera med lösenord
Välj ett lösenord
Spara dokumentet
När du sedan ska skicka detta dokument så ska du skicka dokumentet och lösenordet i två separata mail. Ett annat alternativ är att skicka lösenordet i en helt annan kommunikationskanal, t.ex. Skype. Det är ännu säkrare.
Testa anrop
Nu har vi alla delar på plats. Nu kan vi testa ett anrop mot ditt API med den användare vi har skapat.
Testa från DevPortal
Surfa in på webbadressen till WSO2 API Manager Developer Portal, denna adress slutar på: /devportal
Gå in på fliken “APIs” och välj det API du vill testa anrop mot.
Gå in på fliken “Try Out” i menyn till vänster.
Välj vilken säkerhetstyp du vill använda under “Security Type”.
Välj vilken användare du vill använda i anropet under “Applications”.
Välj vilken nyckel du vill använda under “Key Type”.
Klicka på knappen “GET TEST KEY” för att generera en testnyckel. Denna nyckel påverkar inte de nycklar vi genererade i det tidigare steget.
Välj vilken “Gateway” du vill gå via.
Scrolla ned och välj vilket anrop du vill utföra.
Klicka på “Try it out” och sedan “Execute” så utförs anropet.
Testa från Postman
Om du vill testa ett anrop från postman så kan du importera anropet från det tidigare test vi utförde i DevPortal.
När du har utfört ett anrop från DevPortal så kan du se följande:
Kopiera allt innehåll i textrutan under “Curl”.
Öppna Postman och klicka på “Import” uppe till vänster.
Välj fliken “Raw text”.
Klistra in din kopierade text.
Klicka på “Continue” och sedan “Import”.
Nu har du anropet i Postman och kan klicka på “Send” för att utföra anropet.
Den access token som används här är en så kallad “Test key”. Giltigheten av denna kommer så småningom löpa ut. Om du vill fortsätta testa anrop måste du generera en ny access token. Detta kan du göra på följande sätt:
Surfa in på webbadressen till WSO2 API Manager Developer Portal, denna adress slutar på: /devportal
Gå in på fliken “Applications”.
Gå in på den användare du vill generera en access token för.
Välj antingen att gå in på “Production Keys” eller “Sandbox Keys”.
Gå sedan in på “Oauth2 Tokens”.
Klicka på knappen “GENERATE ACCESS TOKEN”.
Klicka på “GENERATE”.
Du kan nu se din access token. Kopiera denna.
I Postman, gå in på fliken “Headers” i ditt anrop.
Byt ut värdet på din “Authorization”-header. Den ska bestå av: “Bearer <din nya access token>”
Nu ska anropet fungera igen.