Azure APIM configuration

Overview

In this guide, you will learn how to create the APIM configuration and routing in Grand Central.

Key learning outcomes

Learn the key concepts of APIM.
Learn how to manage APIM through applications-live.

APIM architecture overview

The following diagram shows the architecture of a connector running within the Grand Central Platform. This exercise focuses on the APIM components; how to configure the APIM so the connector can be called. The APIM components are configured at a runtime level with the configuration located at the runtimes/$/apim directory in the Grand Central DevHub Application Live repository of your installation: https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/tree/main/runtimes/{runtime}/apim

Replace {installation} and {runtime} values in the preceding URL with the actual values for your environment.

You deploy these configurations using Helm charts by providing the YAML file in Applications Live.

The supported components are:

APIs
API Version Sets
Backends
Products
Subscriptions

API

The API deployment is configured in runtimes/$/apim/apis directory of your installation: https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/tree/main/runtimes/{runtime}/apim/apis

Replace {installation} and {runtime} values in the preceding URL with the actual values for your environment.

Create an Argo Helm chart to deploy the API. The following example shows how to create a Generic API. The format is the same for all APIs, but with different values. Read the comments carefully. Every installation has an example deployment configured with comments. See the generic API example at: https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/blob/main/runtimes/{runtime}/apim/apis/generic-api.yaml

YAML Key Path	Value from Example	Description
`metadata.name`	`grandcentral-generic-api`	The ArgoCD Application Name. This must be unique within the ArgoCD namespace. It usually follows a convention like [project]-[api-name].
`spec.sources[1].chart`	`grandcentral-generic-api`	The Helm Chart Name. This specifies which chart to pull from the registry (gcshared671.azurecr.io/charts). You must update this to the actual name of the connector API chart you are deploying.
`spec.sources[1].targetRevision`	`1.1.9`	The Chart Version. This dictates the specific version of the Helm chart you want to deploy. The version can be retrieved from the API repository CI/CD publishing.
`spec.sources[1].helm.releaseName`	`grandcentral-generic-api-v1`	The Helm Release Name. This is the name Helm uses to track the release inside the Kubernetes cluster. It should generally match or be similar to metadata.name to avoid conflicts.

API Version Sets

Each API needs a corresponding API Version Set configured. The version sets are configured for your installation at: https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/blob/main/runtimes/{runtime}/apim/apiversionsets.values.yaml

Replace {installation} and {runtime} values in the preceding URL with the actual values for your environment.

apiVersionSets:
  - name: grandcentral-generic-api

The version set name should match the metadata.name value of your API.

Backends

An APIM Backend is a configuration that represents the actual connector service your API sends requests to. Below is a sample backend configuration. For your installation, backends are configured at: https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/blob/main/runtimes/{runtime}/apim/backends.values.yaml

Replace {installation} and {runtime} values in the preceding URL with the actual values for your environment.

For more information, see the “Backends Configuration Example” section in the apim/readme.md file.

backends:
  - name: grandcentral-generic-connector
    url: "https://connector-v1-grandcentral.{runtime}.${installation}.gcservices.io"
    title: "GC Generic Connector v1"
    description: "Grand Central Generic (template) connector"

URL pattern for Connector deployment

https://${releasename}-{namespace}.{runtime}.{installation}.gcservices.io

YAML Key	Explanation
`backends`	The list definition that registers external services (targets) within APIM.
`name`	The internal ID used in your policies (e.g., set-backend-service) to reference this specific service.
`url`	The actual destination address (endpoint) where the traffic is forwarded. The kservice URI.
`title`	The friendly display name shown to administrators in the Azure Portal.
`description`	Documentation text explaining the purpose of this backend service.

Products

An APIM Product is a bundle that groups API implementations together and binds the API with its specific one or more implementations and defines various policies to route and control API requests. In your installation, products are configured at: https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/blob/main/runtimes/{runtime}/apim/products.values.yaml The following example shows a product configuration with details of each field:

products:
  - name: "gc-generic-product"
    description: "Grand Central Generic product"
    displayName: "GC Generic Product"
    approvalRequired: "false"
    policy:
      value: |
        <policies>
          <inbound>
            <base/>
            <choose>
              <when condition='@(context.Api.Id == "grandcentral-generic-api-1")'>
                <set-backend-service backend-id="grandcentral-generic-connector"/>
              </when>
              <otherwise/>
            </choose>
          </inbound>
          <backend>
            <base/>
          </backend>
          <outbound>
            <base/>
          </outbound>
          <on-error>
            <base/>
          </on-error>
        </policies>
    productApis:
      - apiName: "grandcentral-generic-api-1"

YAML Key / XML Tag	Description
`name`	Unique ID for this bundle.
`approvalRequired`	If “false”, new API keys are active immediately without admin review.
`policy.value`	The XML logic container that applies to every API grouped inside this product.
`<choose><when/>`	The conditional block that checks if the current request matches the specific API ID defined in productApis.
`<set-backend-service/>`	The routing directive that forwards traffic to the target service. The backend-id must match the name in your Backend config.
`productApis`	The list of APIs included in this bundle. Enables access via the Subscription key.

Subscriptions

In calling a template connector exercise previously you learned how to retrieve a subscription key from the APIM portal. This section shows how to create those subscriptions. A subscription (API key) grants a client access to a specific API(s) and its implementation(s). For your installation, you manage subscriptions at: Subscriptions Configuration For more information, see the “Subscriptions Configuration Example” section in the apim/readme.md file.

subscriptions:
  - name: generic-connector-subscription
    productScope: gc-generic-product

YAML Key	Explanation
`subscriptions`	The list definition that creates access keys for consumers.
`name`	The unique ID for this specific subscription (key).
`productScope`	The specific “Product” (group of APIs) this key is allowed to access. Must match the value from the products configuration

Overview

Capabilities

Developer guides

Security and reliability

Platform administration

Reference

Overview

Key learning outcomes

APIM architecture overview

The supported components are:

API

API Version Sets

Backends

URL pattern for Connector deployment

Products

Subscriptions

​Overview

​Key learning outcomes

​APIM architecture overview

​The supported components are:

​API

​API Version Sets

​Backends

​URL pattern for Connector deployment

​Products

​Subscriptions

Overview

Key learning outcomes

APIM architecture overview

The supported components are:

API

API Version Sets

Backends

URL pattern for Connector deployment

Products

Subscriptions