eBizTalk - Berichten, Unterhalten, Weiterbilden

This article is the 7th in a series about API Management. It aims to uncover the complexities that might come your way when considering introducing API Management in large organisations. This part is a bit of a side-track to this. In recent days I came across the requirement to design a solution where APIs of different organisational units share the same API Management system (Azure API Management). The challenge was to define a way APIs can be managed and usage of the common infrastructure can be evaluated for future cost-splitting between the business units.

Of cause, we use tags to manage resources

The decision on how to enable management of resources was an easy one. Of cause, we use tags for this.

Naming conventions and tagging are ways to add information and meta-data to your cloud infrastructure component to make them easily searchable and manageable. The benefits are also confirmed by the Microsoft Decision Guide of the Cloud Adoption framework.

• Resource management

- Ownership, environments... These tags make it easier to find resources

• Cost management and optimization

- Cost allocation and budgeting can be enabled through tags

• Operations management

- SLA information in a tag is important for operations

• Security

- Confidentiality information for example can help when confirming access permissions

• Governance and compliance

- Governing policies can be managed and applied using tags.

• Automation

- Information relevant for automatic maintenance can be saved in tags. One example is “ExpireOn: …" resources could be automatically deleted at that date to reduce infrastructure costs.

• Workload optimization

- Information about which processes require the resource enable a deeper and quicker analysis to resolve overarching issues

The following chart also illustrates the benefits clearly.

Source: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/decision-guides/resource-tagging/

Ways to add tags 

Now that we established that it is useful to tag your resources and that APIs are no exception to the case, we look at how this can be done.

As adding a tag to a resource is part of “managing your resources” the ways of adding tags are equal to the ways of how you would provision resources, which can be as follows:

1. Portal/ User interface of cloud provider

2. Application Programming Interface (API) of the provider

3. Infrastructure as Code solution supported by the cloud provider. (see my other articles about IaC)

Additionally, specific to Microsoft Azure you can use the following:

4. In Azure you can use the “Azure Cloud Shell”

5. In Azure you can also use the PowerShell “AZ” Library

6. Azure Resource Manager templates (ARM-templates)

This might seem like a lot. And, frankly, it is. The freedom offered by this bouquet of option is necessary, however, to fill the need of every larger organisation with security or operational constrains.

Below image describes how the different ways integrate with Azure. It shows the four ways of resource management offered by Microsoft. Other ways build on top of this. If you have been thinking about using terraform for example, it builds on top of the Azure CLI.

Source: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview

Microsoft claims that those methods are at least as powerful as the Azure portal if not more so as it takes up to 180 days to implement some features in the portal. (src) This is not always true I found, but more on this further down.

Adding tags via... the Portal

The first and most straight forward way is by accessing the management portal of your cloud provider. In azure this is portal.azure.com. Below screenshot illustrates where to change tags of an API Management resource in the azure portal if needed.

This screenshot illustrates where to change tags of an API.

This might be a comfortable way of doing it the first time around. But considering larger organisations, every time one of those properties change that have been added as a tag, someone needs to manually go into the portal to update those tags. This might not be the desired solution for many.

Adding tags via … PowerShell & CLI

I will be looking at PowerShell in this part as the CLI and PowerShell are very similar.

Before you can manage resources, you need to install the az module PowerShell needs to enable Azure resource management. Once PowerShell is prepared you can add tags to Azure resources using blow PowerShell snippet as example. It adds tags to the resource. A similar example for how to accomplish this using the CLI can be found here.

``` PowerShell

$tags = @{"Dept"="Finance"; "Status"="Normal"}

Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Merge

```

HOWEVER, and this is the critical part when talking about APIs, this needs to be supported by the data-model of the resource.

Looking at the model of an API Management you can see that it supports tags to be assigned:

..

Location                          : West Europe

Sku : Consumption

...

SystemCertificates        :

Tags                                 :{}

AdditionalRegions         :{}

….

Looking at the model of API resources however shows that here the Tag property is missing:

ApiId                         : 691b7d410125414a929c108541c60e06

Name                          : echoapiv4

Description                   : Create Echo Api V4

ServiceUrl                    : https://echoapi.cloudapp.net/v4

Path                          : echov3

ApiType                       : http

Protocols                     : {Http, Https}

AuthorizationServerId         :

AuthorizationScope            :

OpenidProviderId              :

BearerTokenSendingMethod      : {}

SubscriptionKeyHeaderName     : Ocp-Apim-Subscription-Key

SubscriptionKeyQueryParamName : subscription-key

ApiRevision                   : 1

ApiVersion                    : v4

IsCurrent                     : True

IsOnline                      : False

SubscriptionRequired          : True

ApiRevisionDescription        :

ApiVersionSetDescription      :

ApiVersionSetId               : /subscriptions/subid/resourceGroups/Api-Default-West-US/providers/Microsoft.ApiManagement/service/contoso/apiVersionSets/xmsVersionSet

Id                            : /subscriptions/subid/resourceGroups/Api-Default-West-US/providers/Microsoft.ApiManagement/service/contoso/apis/691b7d410125414a929c108541c60e06   

ResourceGroupName             : Api-Default-West-US

ServiceName                   : contoso

This missing property has the logical effect that you CAN NOT add tags to APIs via PowerShell. This issue is reported to Microsoft and is currently open.

Adding tags via … REST

Looking at the alternative ways of managing resources in Azure the Management API of Azure comes to mind. This is a REST endpoint offering about the same functionality as PowerShell’s Az module does.

The documentation of the operation we need to add tags to an API Management resource can be found on the documentation website of the same.

…

Now looking at the endpoint to manage APIs you can see that there is, again, no tag property available. Microsoft instead offers a separate endpoint to manage tags of an API.

The process of adding a tag to an API is as follows:

1. Create a tag entity in API Management – link

2. Assign the tag to the API or Operation – link

3. To list tags an API has there is another endpoint – link

Although this might be inconvenient and not very user-friendly, I for my part am happy that it is at all possible.

Adding tags via … ARM

When looking at how tags are added to APIs via the REST API(s) we can assume that tags are separate resources that need to be created and then linked to other resources. This becomes obvious when looking at the ARM templates.

API Management as the parent resource template has APIs and those in turn Operations and, you might guess it, tags as child-resources. But you need to watch out here. This is also a reference to the tag resource. You therefore need to also create the resource of the tag.

The following example would create an API Management with one API (and no operations) where the API displays a single tag “exampletag”.

{

    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

"contentVersion": "1.0.0.0",

    "parameters": {

    },

    "functions": [

    ],

    "variables": {

    },

    "resources": [

        {

            "apiVersion": "2017-03-01",

            "name": "Your API Management",

            "type": "Microsoft.ApiManagement/service",

            "location": "West Europe",

            "tags": {

            },

            "sku": {

                "name": "Developer",

                "capacity": "0"

            },

            "properties": {

                "publisherEmail": "mail@mail.com",

                "publisherName": "Your Name"

            }

        },

        {

            "name": "An API",

            "type": "Microsoft.ApiManagement/service/apis",

            "apiVersion": "2019-12-01",

            "properties": {

                "displayName": "Example API Name",

                "description": "Description for example API",

                "serviceUrl": "https://example.net",

                "path": "exampleapipath",

                "protocols": [

                    "HTTPS"

                ]

            },

            "resources": [

                {

                    "name": "YOUR_TAG_NAME",

                    "type": "Microsoft.ApiManagement/service/apis/tags",

                    "apiVersion": "2019-12-01"

                }

            ]

        },

        {

            "name": "YOUR_TAG_NAME",

            "type": "Microsoft.ApiManagement/service/tags",

            "apiVersion": "2019-12-01",

            "properties": {

"displayName": "exampletag"

            }

        }

    ],

    "outputs": {

    }

}

Adding tags via … other IaC’s

I have checked Terraform and Ansible and am sad to say that neither support API tags. This is because Terraform for example uses the CLI in the background to communicate with Azure and this does not yet have this “feature.”

Unlike with Ansible, using Terraform you can manage APIs and operations. And if any functionality is not available in terraform it does provide the convenient feature of being able to use ARM templates to deploy resources. And those do support tags.

The impact

Although there are many ways, as specially for Azure, to add tags to an API, and most of them are to support automation, not all of them allow this. The impact is that not all use cases are supported.

One of those might be: extending an existing PowerShell script that synchronises APIs with a Data Catalogue (if this feels oddly specific to you, read part 6 of my series). It came as quite the surprise that it was not natively supported by the PowerShell module. It does feel as quite the workaround having to use the API here, but that is just my opinion.

Another use case, thinking of IaC (Infrastructure as code), is that when a workaround needs to be used, the solution becomes unclean and might even introduce unexpected behaviours or related issues.

The reason

Finding the reason for the inconsistent behaviour required a deep dive into the documentation and still I can only voice a hunch. Microsoft correctly claims that APIs support tags. This can be seen on this lengthy list of resources that do not support tags: LINK. The limitations listed on the page of “How to use tags” have one small point, I nearly overread, that states “Tags can't be applied to classic resources such as Cloud Services.” This implies the existence of “Classic resources.”

This is the part where I start guessing. I believe APIs had tag support from the start when they were still a classic resource. When introducing the new resource model type, they (Microsoft) did not update the APIs as the feature was already implemented at the time. This old way of doing it requires us to create a tag resource before assigning it to a resource. Because this is a legacy process it was omitted when implementing the SDK for PowerShell or the CLI.

Facit

Tags are useful to manage, support and secure your APIs. If it is for cost-splitting or for tracking down data due to GDPR requirements, tags can hold relevant information that makes it much quicker and easier to fulfil those tasks.

APIs are no exception there. APIs are however the exception when it comes to tooling consistency and does require a workaround from the developers.

If you want to help solve this problem, you can do so by “liking” the issue that was raised with Microsoft on this topic.

Wer ein SPA-Framework wie Angular zur Entwicklung einer Website nutzt, muss sich früher oder später über das Thema SEO Gedanken machen. Denn anders als bei serverseitigen Frameworks, wie ASP.NET Core, wird das Markup erst durch JavaScript auf dem Client generiert. Ohne zusätzliche Anstrengungen, findet die Suchmaschine also bei der Indizierung keine Inhalte.

Serverseitiges Rendering (SSR) wäre in diesem Fall die naheliegendste Option. Dabei wird das Markup beim Aufruf einer Seite schon auf dem Server bereitgestellt und dann an den Client zurückgeliefert. In meinem Fall sollte die Website allerdings möglichst kostengünstig in einem Azure Storage Account als statische Website gehostet und serverseitige Funktionalität verbrauchsbasiert durch Azure Functions abgebildet werden. Dadurch besteht beim Aufruf der Seite keine Möglichkeit serverseitigen Code auszuführen, weshalb ich eine andere Option in Erwägung ziehen musste – Prerendering beim Build. Dabei wird die SPA während des Builds in einer lokalen Webserver-Instanz ausgeführt, alle Routen aufgerufen und das gerenderte Markup als statische HTML-Seiten gespeichert. Die einzelnen Seiten sind dann entsprechend als physische Dateien mit den notwendigen Inhalten vorhanden.

Für das Prerendering habe ich das npm-Paket angular-prerender verwendet, das wiederum auf dem bekannten Paket angular-universal basiert. Das Ergebnis wird damit in zwei Schritten erreicht:

1. Installation des Pakets (npm install angular-prerender --save-dev)
2. Ausführung der Prerenderings (npx angular-prerender)

Nachdem ich das Ergebnis in den Container im Azure Storage Account kopiert habe, konnten die einzelnen Seiten einwandfrei indiziert und damit über eine Suchmaschine einfach gefunden werden.

Beispiel App:

Ohne Prerendering:

Mit Prerendering:

In diesem Artikel, der bereits der sechste Teil in einer Serie zu API Management ist, erkläre ich, warum es wichtig ist, Transparenz über APIs innerhalb einer Firma zu schaffen und mehrere Möglichkeiten benennen, wie dies mithilfe des API Management ermöglicht werden kann.

„Sharing is the new black“

Das Sprichwort “Sharing is the new black.” wird häufig verwendet, um den Trend zu beschreiben, dass viele ihre monatlichen Abos, von zum Beispiel Netflix oder Spotify, mit Freunden teilen, um so Kosten zu sparen.

Einen ähnlichen Trend sieht man auch schon seit Längerem in der Data Governance. Die Schwerpunktbereiche der Data Governance liegen in der Verbesserung von Verfügbarkeit, Usability, Konsistenz, Integrität und dem Schutz von Daten. “Die Datenverwaltung umfasst die Personen, Prozesse und Informationstechnologien, die erforderlich sind, um einen konsistenten und ordnungsgemäßen Umgang mit den Daten einer Organisation im gesamten Unternehmen zu erstellen.” (quelle). Es ist also im Sinne der Organisation, interne Daten und Datenquellen wiederzuverwenden. Die Gründe liegen auf der Hand:

• Nur bekannte Risiken können vermieden werden. Wenn bestimmte Datenzusammenhänge nicht geschaffen werden können, dann können Risiken auch schnell übersehen werden.
• Standardisierte und wiederverwendete Datenquellen erhöhen die Datenqualität und das Vertrauen in die Daten.
• Vertrauenswürdige Daten verbessern Entscheidungen, Prozesse und sind daher sehr wertvoll. Es können sogar neue Wertschöpfungsketten gebildet werden.

Rolle des API Managements in guter Data Governance

Die meisten großen Unternehmen haben, aus dem einfachen Grund heraus, dass sie historisch so gewachsen sind, in verschiedenen Abteilungen und Unternehmenseinheiten auch unterschiedliche IT Systeme. Ein einfaches Beispiel ist hier das CRM-System. Ob die Abteilungen sich einfach unterschiedliche Systeme angeschafft haben oder ob durch ein Merger ein anderes System der aufgekauften Firma hinzugekommen ist; Fakt ist, dass Entwicklerteams von Applikationen wie zum Beispiel ein Kundenportal, das auf alle unternehmensinternen Kundendaten zugreifen muss auch auf die APIs der verschiedenen Systeme zugreifen müssen.

Wir haben also mehrere Systeme, die gleiche Datentypen über ihre API anbieten. Hier Transparenz zu schaffen ist die Aufgabe eines Daten-Katalogs oder einer API-Library. Letzteres wird durch ein gutes API Management ermöglicht. Wenn APIs in einem zentralen API Management registriert sind, schafft dass die nötige Übersicht für Entwickler, die richtige API oder APIs zu finden. Je nach Fortschritt der API-Strategie werden hier System-APIs oder auch Domain-APIs gefunden, diese würden, um beim Beispiel Kundendaten zu bleiben, über eine API die Kundendaten mehrerer Systeme über nur einen Endpunkt zur Verwaltung anbieten.

Übersicht schaffen bei mehreren API-Management Systemen

Falls Sie auch meine anderen Artikel gelesen haben, oder sich auch gerade mit dem Thema beschäftigen, wissen Sie, dass es gut möglich ist, das Firmen mehr als nur ein API Management System verwenden. Die Frage ergibt sich also: Wie schaffe ich trotzdem eine zentrale Übersicht über alle APIs? Es gibt mehrere Möglichkeiten das zu erreichen.

1. APIs müssen alle zusätzlich im zentralen API Management registriert sein.

2. Es wird ein unabhängiges Tool verwendet, um APIs zu katalogisieren.

In Option 1 werden trotz Verwendung von weiteren API Management Systemen die APIs zusätzlich im zentralisierten, oder auch “common”, API Management registriert. Dies erhält die Zentralität der Steuerung von und Kontrolle über die APIs. Jedoch erhöht es auch die Latenz der Aufrufe minimal. In Fällen wie IoT Lösungen kann dies hinderlich sein.

Das “Common API Management” würde hier die Funktion der API-Library übernehmen können.

Abbildung 1: 2 API Management Systeme in Serie geschalten

Option 2 wäre die Verwendung eins anderen Systems, welche als API-Library fungiert. Mit einer einfachen Integrationslösung können die Daten der vorhandenen APIs aus dem API Management System, das meist auch per API, entnommen und in einem Tool der Wahl hinterlegt werden. APIs bieten in vielen Fällen Daten und Daten-Operationen an. Ein Daten-Katalog würde sich demnach gut für solche Zwecke anbieten.

Abbildung 2: API-Katalog für 2 API Management

Fazit

Es ist essenziell für Firmen einen Überblick über Daten und Datenquellen zu haben. Nur durch Transparenz kann der Wert der gesammelten Daten erst richtig zur Geltung kommen und sogar neue Geschäftsbereiche ermöglichen und die Firma vor Risiken schützen. API Management schafft einen Überblick über die vorhandenen APIs und macht es leichter API-Strategien zur Zentralisierung/Konsolidierung von Datenquellen zu etablieren. Auch wenn mehrere API Management Systeme verwendet werden, ist es wichtig, intern einen Katalog aufzubauen, der für die nötige Transparenz sorgt. Ob das das API Management selbst ist oder ob ein anderes Tool dafür verwendet wird ist hierbei nur Mittel zum Zweck.

Dieser Artikel ist Teil einer Serie zum Thema API Management in großen Unternehmen. Ziel ist es, meine Sicht auf verschiedene Themen zu teilen und die Komplexitäten aufzudecken. In diesem Artikel werde ich Fragestellungen behandeln, die mit der Provisionierung von API Management und APIs zu tun haben. Hierfür nehme ich mir Azure API Management als Beispiel.

Viele Möglichkeiten ein API Management zu provisionieren

Wenn man ein API Management aufsetzen möchte, hat man folgende Möglichkeiten das zu erreichen.

• Manuell über das Azure Portal
• Mit PowerShell
• Über die CLI
• Mit Hilfe vom Azure Ressource Manager (ARM)
• Terraform & Ähnlich
• u.v.m.

Welcher Weg jedoch derjenige ist, der für den Anwendungsfall am Sinnvollsten ist, hängt zu 100% davon ab wie das API Management in Zukunft verwendet werden soll. Hierzu empfehle ich auch Teil 4 von dieser Serie zu lesen. Um die Richtige Entscheidung zu treffen, sollte man sich zu den folgenden Anforderungen eine Antwort suchen:

• Wie wichtig ist ein schnelles Desaster-Recovery?
• Werden mehrere Teams das APIM nutzen?
• Gibt es ein Team, welches die Zuständigkeit inne hat?
• Brauchen Änderungen am APIM ein vorheriges Approval?
• Gibt es mehrere Umgebungen (dev, test, prod), die identisch konfiguriert sein müssen?

To IaC or not to IaC

IaC (Infrastructure as Code) ermöglicht, eine gesamte Infrastrukturarchitektur durch die Ausführung eines Skripts zu beschleunigen. Nicht nur können virtuelle Server bereitgestellt werden, sondern auch vorkonfigurierte Datenbanken, Netzwerkinfrastrukturen, Speichersysteme, Lastausgleiche und vieles mehr.

All das kann schnell und einfach für Entwicklungs-, Test- und Produktionsumgebungen konfiguriert werden, was den Softwareentwicklungsprozess wesentlich effizienter machen kann. Außerdem können problemlos Standardinfrastrukturumgebungen in anderen Projekten wiederverwendet werden.

Die Möglichkeit eine gesamte Infrastruktur durch Ausführung eines Skripts zu konfigurieren ist ein großer Vorteil für die, die ein gutes Desaster Recovery benötigen.

Für Hackathons und kleinere Hobby-projekte ist die Komplexität der Konfiguration und auch die organisatorische Hürde sehr gering. Das verleitet gerne dazu, die Cloud-infrastruktur manuell aufzusetzen. Das ist vielleicht für das eine Projekt auch ausreichend. Trotzdem empfehle ich auch hier die Verwendung von IaC. Der Grund dafür ist, dass die meisten Architekturen auf die ein oder andere Weise wiederverwendet werden. Ein Lösung, die im Hackathon entwickelt wurde findet häufig auch Anwendung in der Organisation.

Ich empfehle generell die Verwendung von Provisionierungs-Automatisierung. Für große Unternehmen ist der Nutzen nicht wegzudenken und mitigiert viele Risiken. Desasterf Recovery ist hier vielleicht das offensichtlichste Beispiel. Ein weiteres ist jedoch auch der Transfer von Wissen und Knowhow. Es wäre schlecht, wenn das Wissen über die Konfiguration der Infrastruktur zusammen mit dem Mitarbeiter die Firma verlässt.

Organisatorische Bedenken

Im vorangehenden Kapitel habe ich meine klare Empfehlung ausgesprochen IaC zu verwenden. In großen Firmen, die aus verschiedenen Gründen die einfachsten Sicherheitsanforderungen an die Infrastruktur generell haben, sind beim Einsatz von IaC jedoch einige Dinge zu beachten.

Viele Firmen haben mehrere IT-Entwicklungsprojekte und Teams. Die Frage ergibt sich also in wie weit diese Teams die gleichen Komponenten der Infrastruktur wiederverwenden dürfen, sollten oder können. Ein Team- und Projektübergreifendes API Management zum Beispiel stellt klare Fragen an die Sicherheit. Aber wie viel Kontrolle erhalten die einzelnen Teams auf das API Management? Wie verhindert man, dass Teams sich nicht gegenseitig Probleme bereiten?

Im Folgenden möchte ich 4 Möglichkeiten aufzeigen, die in 1000 Metern Höhe beschreiben, wie API Management in den verschiedenen Teams verwendet werden könnte.

Im ersten und einfachsten Fall verwendet jedes Entwicklungsteam sein eigenes API Management, welches durch das IaC-Tool der Wahl provisioniert wird. Es kann nur das zuständige Team die Konfiguration des API Managements ändern und ist somit auch zu 100% zuständig für die Prozesse die damit einhergehen. Ein Vorteil von dieser Struktur ist, dass Teams sehr unabhängig agieren können, was die Entwicklungsgeschwindigkeit erhöht.

Abbildung 1: Infrastruktur Entwicklungsprozess in unabhängigen Teams

Wenn sich die Organisation dazu entschieden hat, das API Management zu zentralisieren, um zum Beispiel zentrale Kontrolle über die Sicherheitsmaßnahmen und Zugriffssteuerung zu haben oder einfach im Budget einzusparen, dann stellt sich die Frage wie die Entwicklung und Provisionierung des API Managements dann vonstatten geht.

Hier gibt es mehrere Möglichkeiten.

• Man erlaubt den Teams, ähnlich einer open-source Lösung, an der gemeinsamen Konfiguration des API Managements mitzuwirken.
• Man erlaubt es ihnen, APIs in ein bestehendes APIM direkt zu provisionieren.
• Man erlaubt es nur indirekt über eine API die Provisionierung von APIs.

Welche dieser Möglichkeiten die richtige ist hängt von den Anforderungen ab und ist auch zum großen Teil Geschmacksache. Erlauben die Sicherheitsanforderungen es, dass Teams die Definition von APIs der jeweils anderen sehen dürfen? In welchem Ausmaß haben die Teams die Kontrolle über eigene APIs und dürfen von den Funktionalitäten des API Managements Gebrauch machen?

Möglichkeit 1 bedeutet, dass die gesamte Konfiguration vom API Management in, zum Beispiel, einem Git-repository liegt, auf das  die Teams Zugriff haben. Jedes Team würde im Laufe seiner Entwicklungsphasen Änderungen des API Management vorschlagen. Eine Änderung könnte beinhalten, eine weitere API hinzuzufügen oder zu entfernen, könnte aber auch beinhalten, dass bestimmte Protokolle oder Zertifikate verwendet werden müssen. Team A, welches dafür zuständig ist, das API Management und die APIs sauber und sicher zu halten, würde die vorgeschlagenen Änderungen kontrollieren und evaluieren ob die Änderungen auch andere APIs beeinflussen würden. Wenn die Änderung akzeptabel ist, würde die neue Version des Systems oder der Konfiguration angewandt werden.

Möglichkeit 2 entzieht den Teams das Recht, API Management-weite Änderungen zu unternehmen. Die Teams dürfen APIs anlegen, können jedoch nicht mehr konfigurieren, ob das gesamte API Management zum Beispiel isoliert in einem V-netz ist oder nicht. Diese Entscheidung bleibt Team A vorbehalten.