@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.

$3

@azbake/ingredient-apim-api

$3

``yaml
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
`

$3


`yaml
recipe:
apim-api-deploy:
properties:
type: "@azbake/ingredient-apim-api" #ingredient type
source: "/" #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

`yaml
options:
apiWaitSeconds: # 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: # 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 of times the ingredient will retry to add the API
apiRetryWaitTime: # seconds between retries
`

apis

`yaml
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: #unique id for the API (version set) - required
versions:
- versionSchema #See next section for version schema
`

api[n].versions

`yaml
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: #typically you want set the id to - to keep the id consistant for the version set it belongs to - required
version: #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

`yaml
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: #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

`yaml
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: #required name of diagnostics settings
`

Utility Functions

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

$3

| Function | Returns | Description |
|----------|---------|-------------|
| get_api(resourceGroup: string, apimName: string, apiId: string) | Promise | Returns the API for a given set of parameters. |
| get_backend(resourceGroup: string, apimName: string, backendId: string) | Promise | 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 |

$3


`yaml
variables:
api: "[await apimapi.get_api(, , )]"
backend: "[await apimapi.get_backend(, , )]"
hostHeader: "[await apimapi.get_hostheader(, )]"
swaggerUrl: "[await apimapi.get_swaggerUrl(, ), ]"
`

Sample

`yaml
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:








{{expressionApiDisplay}}



- operation: addPet #override the addPet operation policy
format: xml
value: " "
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:









- operation: addPet #override the addPet operation policy
format: xml
value: " "
``