@azbake/ingredient-apim-api

Changelogs

• @azbake/ingredient-apim-api

Overview

The APIM API ingredient allows for easy registration & modification of APIs within an Azure APIM resource.

Ingredient Name

@azbake/ingredient-apim-api

How to include in a recipe

name: My package
shortName: mypkg
version: 0.0.1
ingredients:
  - "@azbake/ingredient-apim-api@~0" #include the latest version of the ingredient at build time
parallelRegions: false #typically we only want to deploy to the primary region, so can turn off parallel deploy
resourceGroup: false #If the recipe only contains an apim api deployment, you don't need to create resource groups

How to use as an ingredient instance

recipe:
  apim-api-deploy:
    properties:
      type: "@azbake/ingredient-apim-api" #ingredient type
      source: "<azure_resource_group_name>/<azure_apim_resource_name>" #identity the azure apim resource to register an API against
      condition: "[coreutils.primary_region()]" #make sure we only execute this against the primary region for multi-region configs
      parameters:
        ... #see documentation below on parameter documentation for how to use.

Parameters

Here is the documentation for all the supported paremeters for this ingredient.

options

options:
  apiWaitSeconds: <number>   # Supply a number of seconds to wait for any xml-link/swagger-link urls to become availabile 
                             # before creating the APIM api/policy/etc.
                             # You might be deploying a new API in this recipe, which could take 30-120s to become online.
                             # This setting lets us wait for new APIs to be online
  forceWait: <boolean>       # forces bake to wait the `apiWaitSeconds` value even if the API exists. Useful for allowing a
                             # k8s service deployment to update when using the same version.
  apiRetries: <number>       # number of times the ingredient will retry to add the API
  apiRetryWaitTime: <number> # seconds between retries      

apis

apis: #follows this azure spec for *ApiVersionSetContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3215
  - name: <api-version-name> #unique id for the API (version set) - required
    versions:
      - versionSchema #See next section for version schema

api[n].versions

versions: #follows this azure spec for *ApiCreateOrUpdateParameter* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L180
  - name: <api-name> #typically you want set the id to <api-version-id>-<version> to keep the id consistant for the version set it belongs to - required
    version: <string> #version string that will be used as part of the above ApiVersionSetContract.versioningSchema
    products: #optional list of product names to assign API to
    policies: #see next section for policy schema
    diagnostics: #see next section for diagnostic schema

Note: ApiCreateOrUpdateParameter.serviceUrl and ApiCreateOrUpdateParameter.value support being defined as BakeVariables. This allows you to set these two values as an expression to resolve endpoint/data dynamically during deployment

api.versions[n].policies

policies: #scheme follows this azure spec for *PolicyContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3097
  - operation: <string> #optional, and if not set this will be the default policy set for the entire api. Otherwise, name of an operation within this api to apply the policy to.

api.versions[n].diagnostics

diagnostics: #follows this azure spec for *DiagnosticSettingsResource* : https://github.com/Azure/azure-sdk-for-js/blob/20fe312b1122b21811f9364e3d95fe77202e6466/sdk/monitor/arm-monitor/src/models/index.ts#L991
  - name: <diagnostics name> #required name of diagnostics settings

Utility Functions

Utility classes can be used inside of the bake.yaml file for parameter and source values.

apimapi class

Function	Returns	Description
get_api(resourceGroup: string, apimName: string, apiId: string)	Promise<ApiGetResponse>	Returns the API for a given set of parameters.
get_backend(resourceGroup: string, apimName: string, backendId: string)	Promise<BackendGetResponse>	Returns the back end for a given set of parameters.
get_hostheader(namespace: string, k8sHostname: string, serviceName: string)	string	Returns host header for API
get_swaggerUrl(namespace: string, k8sHostname: string, version: string, serviceName: string, protocol: string)	string	Returns swagger url page for the API

Utility function examples

variables:
  api: "[await apimapi.get_api(<apim resource group>, <apim name>, <api id>)]"
  backend: "[await apimapi.get_backend(<apim resource group>, <apim name>, <backend id>)]"
  hostHeader: "[await apimapi.get_hostheader(<api namespace>, <k8sHostName>)]"
  swaggerUrl: "[await apimapi.get_swaggerUrl(<api namespace>, <k8sHostName>), <api version>]"

Sample

name: my-api
shortName: myApi
owner: owner
version: 1.0.0
ingredients:
  - "@azbake/ingredient-apim-api@~0"
  - "@azbake/ingredient-app-insights@~0"
resourceGroup: false #no need to create a resource group, just assigning to existing APIM instance
parallelRegions: false
variables:  
  url: http://petstore.swagger.io/v2/swagger.json
  aiName: "[appinsights.get_resource_name('apim-api')]"
  apimName: "[apim.get_resource_name('api')]"
  apimResourceGroup: "[apim.get_resource_group()]"
  # build the source from helper functions
  apimSource: "[apim.get_resource_group() + '/' + apim.get_resource_name('api')]"
recipe:
  my-api-deploy:
    properties:
      type: "@azbake/ingredient-apim-api"
      source: "[coreutils.variable('apimSource')]" #point to existing APIM resource to add API
      condition: "[coreutils.primary_region()]"
      parameters:
        options:
          apiWaitTime: 60 # override to waiting up to 60s for the API to be ready
          forceWait: true # force wait 60s before updating the API in APIM
          apiRetries: 2 # retry adding the API this number of times
          apiRetryWaitTime: 5 # number of seconds between retries
        apis:
          - name: petstore #unique API version identifier across APIM
            displayName: Pet Store API
            description: Pet Store API description
            versioningScheme: Segment
            versions:
              - name: petstore-v1 # unique API identifer across APIM
                version: v1
                apiType: http
                path: pets #base apim url for this api
                protocols: #array of http and/or https
                  - https
                format: swagger-link-json #using a swagger link the value needs to be a http based json document to download
                value: "[coreutils.variable('url')]" #value supports bake variables.
                products:
                  - petstore-product #product should already be created.  if needed you can import APIM ingredient and deploy in the same recipe
                  - starter
                policies: 
                  - format: xml #we use a non-link format here to embed the policy, but this could have been xml-link and a http address
                    value: <policies>
                              <inbound /> 
                              <backend>    
                                <forward-request /> 
                              </backend>  
                              <outbound>
                                <set-header name="X-Powered-By" exists-action="delete" />
                                <set-header name="X-AspNet-Version" exists-action="delete" />
                                <set-header name="CustomHeader" exists-action="override">
                                  <value>{{expressionApiDisplay}}</value>
                                </set-header>
                              </outbound>
                            </policies>
                  - operation: addPet #override the addPet operation policy
                    format: xml
                    value: "<policies> <inbound /> <backend>    </backend>  <outbound /></policies>"
                diagnostics:
                  - name: applicationinsights
                    loggerId: "[(await apim.get_logger(await coreutils.variable('apimResourceGroup'), await coreutils.variable('apimName'), 'aiapim-api')).id]"
                    sampling:
                      samplingType: fixed
                      percentage: 50
              - name: petstore-v2 # unique API identifer across APIM
                version: v2
                apiType: http #unless you're using soap
                path: pets #base apim url for this api
                protocols: #array of http and/or https
                  - https
                format: swagger-link-json #using a swagger link the value needs to be a http based json document to download
                value: "[coreutils.variable('url')]" #value supports bake variables.
                products:
                  - petstore-product
                policies:
                  - format: xml #we use a non-link format here to embed the policy, but this could have been xml-link and a http address
                    value: <policies>
                              <inbound /> 
                              <backend>    
                                <forward-request /> 
                              </backend>  
                              <outbound>
                                <set-header name="X-Powered-By" exists-action="delete" />
                                <set-header name="X-AspNet-Version" exists-action="delete" />
                              </outbound>
                            </policies>
                  - operation: addPet #override the addPet operation policy
                    format: xml
                    value: "<policies> <inbound /> <backend>    </backend>  <outbound /></policies>"