Skip to main content

​
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 PathValue from ExampleDescription
metadata.namegrandcentral-generic-apiThe ArgoCD Application Name. This must be unique within the ArgoCD namespace. It usually follows a convention like [project]-[api-name].
spec.sources[1].chartgrandcentral-generic-apiThe 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].targetRevision1.1.9The 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.releaseNamegrandcentral-generic-api-v1The 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 KeyExplanation
backendsThe list definition that registers external services (targets) within APIM.
nameThe internal ID used in your policies (e.g., set-backend-service) to reference this specific service.
urlThe actual destination address (endpoint) where the traffic is forwarded. The kservice URI.
titleThe friendly display name shown to administrators in the Azure Portal.
descriptionDocumentation 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 TagDescription
nameUnique ID for this bundle.
approvalRequiredIf “false”, new API keys are active immediately without admin review.
policy.valueThe 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.
productApisThe 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 KeyExplanation
subscriptionsThe list definition that creates access keys for consumers.
nameThe unique ID for this specific subscription (key).
productScopeThe specific “Product” (group of APIs) this key is allowed to access. Must match the value from the products configuration