fb
Nieuws 8 min

Een API maken met API manager 4.1

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
api manager
Scroll

De nieuwe WSO2 API manager 4.1 is een incrementele update van versie 4.0. Het 4.x-versiebereik van het product bracht aanzienlijke veranderingen met zich mee, ook ten opzichte van de uitgaande 3.x-versies. Een van de grote veranderingen die we nu zien, is dat het integratieprofiel en het API-managerprofiel dichter bij elkaar zijn. Aan de andere kant heeft internet weinig besef van afstand.

Hiermee bedoel ik dat het niet uitmaakt of een proxy op dezelfde server draait of op een andere server in een ander datacenter. In dit blok ga ik kijken naar het belangrijkste van de API-manager: een API maken.

Wat is nieuw? Hoe is het maken van een API veranderd? Zijn er nieuwe dingen die we kunnen doen en oude dingen die we niet meer kunnen doen? Zullen we erin duiken en erachter komen?

Nieuw architectuur Api manager 4.1

Graphical user interface, application

Description automatically generated

In de documentatie vind je het overzicht van de nieuwe architectuur waar je duidelijk de aanwezigheid van een streaming- en micro integrator kunt zien. Het is echter geen onderdeel van de download.

Als je naar de installatie van API manager 4.0.0 kijkt, dan kijk je naar een download van 432 megabyte. Dit komt ongeveer overeen met de download van de API manager 3.2.0 (445MB). Het lijkt er dus op dat er niet heel veel is toegevoegd, tenzij er natuurlijk iets is verwisseld.

Volgens de compatibiliteitsmatrix werkt API Manager 4.0.0 voor Java 8 en Java 11. Volgens WSO2 is API Manager 4.0.0 gebaseerd op WSO2 Carbon 4.6.1 en zal naar verwachting compatibel zijn met alle WSO2-producten die zijn gebaseerd op een Carbon 4.6.x-versie.

Om het beheersbaar te houden, ga ik me concentreren op het maken van een API die de veranderingen identificeert die er zijn. Ik zal niet ingaan op de talloze andere wijzigingen in het product.

Opstarten van de API-manager

Met mijn huidige Java-versie (AdoptOpenJDK, build 1.8.0_282-b08) start ik de API-manager. Hier vinden we een van de eerste wijzigingen waarbij de bekende wso2server.sh of bat nu is vervangen door een nieuw commando: apimanager.sh of bat. We hoeven alleen maar op het bestand te klikken of, als je Linux gebruikt, te starten vanuit een terminalsessie.

Het begint eigenlijk zoals we het voorheen deden, met de publisher-dev-portal en carbon-console die als URL’s worden weergegeven.

[2021-09-07 10:45:39,559]  INFO – CarbonUIServiceComponent Mgt Console URL  : https://localhost:9443/carbon/

[2021-09-07 10:45:39,559]  INFO – CarbonUIServiceComponent API Developer Portal Default Context : https://localhost:9443/devportal

[2021-09-07 10:45:39,559]  INFO – CarbonUIServiceComponent API Publisher Default Context : https://localhost:9443/publisher

Laten we de publisher starten

Graphical user interface, application

Description automatically generated

Graphical user interface, application

Description automatically generated

Er is dus een nieuwe interface die we kunnen zien wanneer we inloggen. De afbeeldingen zijn nieuw; de functionaliteit is echter gedeeltelijk hetzelfde. In eerdere versies waren we in staat om REST-API’s te maken die werken met soapservices [ik noem deze geen API’s omdat API’s voor mij uitsluitend REST zijn]. De grafiek QL was ook beschikbaar. Alleen de API-streaming is nieuw, maar als we erop klikken, vinden we een andere mogelijkheid die we hebben kunnen gebruiken: Websockets.

Als je op elke tegel klikt, zie je goed wat je kunt doen:

en zoals je kunt zien is het een combinatie van bekende functionaliteit samen met een aantal compleet nieuwe functionaliteiten zoals webhook API, SSE API en async API. Deze zijn compleet nieuw en bieden weer nieuwe functionaliteit. Ik weet niet zeker of ik ze per se API’s zou noemen vanwege de eerder genoemde verbinding van API met REST. Maar toch is het een verlenging van het product. Voor deze eerste blog over API-miniature 4.1 ga ik me concentreren op de echte REST-API helemaal vanaf het begin.

Een API maken vanuit het niets

Laten we een nieuwe API ontwerpen. Klik op helemaal opnieuw beginnen en laten we eens kijken wat het volgende venster inhoudt.

Dus, ik zou zeggen dat dit een bekende interface is in vergelijking met de vorige interface. We hebben nu een kleinere lijst om in te voeren omdat de bedrijfsplannen nu niet langer deel uitmaken van de eerste stap.

Laten we dus een eerste API maken met de naam myfirstAPI. Vul de gegevens zo in.

Graphical user interface, application

Description automatically generated

Druk op Create & Publish en je kunt zien dat de API is aangemaakt.

Graphical user interface

Description automatically generated

We kunnen de API nu rechtstreeks vanuit de ontwikkelaarsportal uitproberen. Dit is echter geen nieuwe functionaliteit; De functie is ook beschikbaar in 3.2.0.

Zoals je in het overzicht kunt zien, zijn de bekende wildcard-resources gemaakt op GET POST PUT DELETE en PATCH, evenals het bedrijfsplan dat nu is ingesteld op onbeperkt. Hiermee kun je snel een API maken, maar het echte gebruik van een dergelijke API is uiterst beperkt. De reden waarom ik dit zeg, is dat zowel de wildcard resources als het onbeperkte bedrijfsplan een typische “doe dat niet” zijn als het gaat om API-definitie. Je wilt de resources echt zo veel mogelijk vastleggen, alleen diegenen aanbieden die compatibel zijn met de back-end, terwijl je ook de criteria beperkt van invoer die door de genoemde resources worden geaccepteerd. Het onbeperkte bedrijfsplan is ook iets dat je normaal gesproken niet zou gebruiken, omdat het de mogelijkheid van beperking wegneemt.

Maar laten we onze API toch eens uitproberen, aangezien dit slechts een eenvoudige testopstelling is. Laten we de try-out-functionaliteit selecteren vanuit de publisher. Je vindt het in de linkerbenedenhoek net boven het tabblad Levenscyclus.

Graphical user interface, application

Description automatically generated

Ik heb de sleutel gegenereerd, een JWT-sleutel die nodig is om de API aan te roepen, omdat deze standaard is ingeschakeld. Klik op de get-knop.

Graphical user interface, application

Description automatically generated

Zoals je kunt zien, wordt de GET resource van de API met succes aangeroepen.

Laten we nu eens kijken hoe de nieuwe API Manager de API-elementen weergeeft.

Nieuwe lay-out

Met de nieuwe versie is de de publisher lay-out nu vernieuwd. Laten we eens kijken naar enkele van de nieuwe interessante toevoegingen die met de nieuwe versie zijn geïntroduceerd.

Graphical user interface, application

Description automatically generated

Laten we eerst eens kijken naar de basisinformatie.

Dit omvat de GitHub-URL en Slack-URL. Daarnaast vinden we ook de bekende elementen van de API-definitie terug.

In alle aspecten duiken gaat iets te ver. Als je geïnteresseerd bent, kun je altijd deelnemen aan onze API Manager 4.1.0 CORE-training om alle aspecten te leren kennen.

De volgende opties zijn ook hetzelfde gebleven, sommige met een kleine verandering wat betreft de volgorde van de velden:

  • Bedrijfsinformatie
  • Abonnementen
  • Documenten
  • Opmerkingen
  • Runtime
  • Resources
  • API-definitie
  • Eindpunten
  • Lokale scopes
  • Eigendommen
  • Inkomsten genereren
  • Levenscyclus
  • Proberen

Implementaties

Implementaties zijn nieuw in deze API Manager-versie. Omdat de API nu in het geheugen is gemaakt (en niet als een op bestanden gebaseerde API-definitie in de Synapse-directory), kunnen we nu revisies implementeren. Ik heb de API met een nieuwe afbeelding gemaakt en die als revisie geïmplementeerd.

Dit was de oude API vanuit het perspectief van de Devportal.

Graphical user interface, text, application, email

Description automatically generated
Graphical user interface, text, application, chat or text message

Description automatically generated
A picture containing chart

Description automatically generated

Nu ziet het er zo uit. Let op: dit blijft binnen de gepubliceerde levenscyclus. Ik kan schakelen tussen revisies en geheel nieuwe revisies implementeren.

Wat zegt de documentatie over revisies ? Nou, best veel eigenlijk. De link toont alle informatie, maar het belangrijkste is het volgende. Om WSO2 te citeren:

Met de introductie van API- en API-productrevisies zijn voorheen gekoppelde publicatie- en implementatieactiviteiten ontkoppeld . De API-uitgever heeft meer controle over de API-implementaties en kan herstelbare wijzigingen aanbrengen in het API-project. API-revisies zijn vergelijkbaar met een controlepunt in het vastleggen van de tijd dat de huidige status van de API vastlegt wanneer de revisie gemaakt is.

Als de wijzigingen een nadelig effect hebben op de API zodra deze is geïmplementeerd in een Gateway-omgeving, kun je snel terugkeren naar een eerdere status van de API. In totaal kun je maximaal vijf revisies hebben, daarna moet je een van de revisies verwijderen.

Door meerdere gateways te definiëren, kun je een revisie testen op de ene gateway en, indien succesvol, deze implementeren op de andere.

Graphical user interface, text, application, email

Description automatically generated

De API vinden

De API-definitie wordt opgeslagen in het governance-register, onder /_system/governance/apimgt/applicationdata/apis/ om precies te zijn. Daar zijn ook alle revisies te vinden. Hieronder de eerste revisie.

Betekent dit dat we de Synapse-configuratiemap niet meer gebruiken? Nee, voor Mediation Extentions gebruiken we nog steeds de sequence directory om de bestanden te uploaden. Je kunt ook het publiceren van api-artefacten naar het bestandssysteem inschakelen zoals voorheen. Als je dit wilt doe je het door bepaalde eigenschappen te wijzigen.

Beleid

Een andere belangrijke functie die is geïntroduceerd in de 4.1-versie is operationeel beleid. In tegenstelling tot eerdere versies is het nu mogelijk om bemiddelingsbeleid per resource te introduceren in API Manager. Vóór versie 4.1 was het alleen mogelijk om beleidsregels toe te voegen in de in/uit-reeksen. (Zie hieronder)

Maar nu is er veel meer flexibiliteit en kun je meerdere beleidsregels slepen en neerzetten in de volgorde waarin je ze wilt laten uitvoeren, zoals hieronder. Je kunt ook zelf beleid definiëren door op de knop “Nieuw beleid toevoegen” te klikken.

Graphical user interface, text, application

Description automatically generated

Opmerking: op het moment dat dit artikel wordt geschreven, biedt API Manager versie 4.1 geen ondersteuning voor de definitie van algemene regels die worden gedeeld tussen meerdere API’s. Operationele regels worden na declaratie samen met de API gebundeld en worden als lokaal beschouwd voor die specifieke API. Dit is een afwijking van het referentiegerelateerde model voor algemene regels dat aanwezig was in eerdere releases (zelfs in 4.0), maar dat nu is verwijderd. Na correspondentie heeft het WSO2-team toegezegd hier ondersteuning voor te bieden (zie kwestie: https: //github.com/wso2/api-manager/issues/111), dus kunnen we verwachten dat het probleem te zijner tijd wordt opgelost en dat het model beschikbaar wordt gemaakt voor gebruik in de vorm van een update.

Ik heb Log Message toegevoegd in de mediationflow van de GET-bron.

Graphical user interface, application

Description automatically generated with medium confidence

Aangezien Publishing and deployment echter is losgekoppeld, moeten we een nieuwe Revision maken en die implementeren.

Dit is echt iets waar je je in moet verdiepen, omdat het verschilt van de manier waarop we dit in het verleden deden. Voor mij als trainer betekent het dat het trainingsmateriaal voor deze nieuwe API Manager 4.1.0 moet worden aangepast, omdat het mechanisme is veranderd.

Conclusie

API Manager 4.x-generatie is een enorme upgrade ten opzichte van eerdere versies. Er zijn een aantal dingen veranderd. Sommige veranderingen zijn slechts cosmetisch en andere veranderingen vormen, zoals we net hebben gezien, nieuwe procedures en mogelijkheden. In komende blogs zal ik ingaan op andere veranderingen en nieuwe dingen die we kunnen doen met de API Manager.