arazzo: 1.0.1
info:
  title: Azure API Management Upsert API
  summary: Find an API by identifier and update it if present, otherwise create it.
  description: >-
    A common API Management onboarding pattern. The workflow lists the APIs on
    the service, branches on whether the target API identifier already exists,
    and then either patches the existing API definition or creates a brand new
    one. Every step spells out its request inline so the flow can be read and
    executed without opening the underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: azureApiManagementApi
  url: ../openapi/microsoft-azure-api-management-rest-api-openapi.yaml
  type: openapi
workflows:
- workflowId: upsert-api
  summary: Upsert an API definition into an API Management service.
  description: >-
    Lists existing APIs, checks for a matching identifier, and either updates
    the matched API description or creates a new API with the supplied display
    name, path, and backend service URL.
  inputs:
    type: object
    required:
    - subscriptionId
    - resourceGroupName
    - serviceName
    - apiId
    - displayName
    - path
    - serviceUrl
    properties:
      subscriptionId:
        type: string
        description: The Azure subscription identifier.
      resourceGroupName:
        type: string
        description: The resource group containing the service.
      serviceName:
        type: string
        description: The API Management service name.
      apiId:
        type: string
        description: The API identifier to upsert.
      displayName:
        type: string
        description: The human-readable API display name.
      description:
        type: string
        description: The API description.
      path:
        type: string
        description: The API URL suffix/path on the gateway.
      serviceUrl:
        type: string
        description: The backend service URL the API proxies to.
  steps:
  - stepId: listApis
    description: >-
      List the APIs already registered on the service so the flow can detect an
      existing definition for the target identifier.
    operationId: Api_ListByService
    parameters:
    - name: subscriptionId
      in: path
      value: $inputs.subscriptionId
    - name: resourceGroupName
      in: path
      value: $inputs.resourceGroupName
    - name: serviceName
      in: path
      value: $inputs.serviceName
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      apiCount: $response.body#/count
    onSuccess:
    - name: apiExists
      type: goto
      stepId: updateApi
      criteria:
      - context: $response.body
        condition: $.value[?(@.name == '$inputs.apiId')]
        type: jsonpath
    - name: apiMissing
      type: goto
      stepId: createApi
      criteria:
      - context: $response.body
        condition: $.count == 0
        type: jsonpath
  - stepId: updateApi
    description: >-
      Patch the existing API with an updated description, leaving other
      properties intact.
    operationId: Api_Update
    parameters:
    - name: subscriptionId
      in: path
      value: $inputs.subscriptionId
    - name: resourceGroupName
      in: path
      value: $inputs.resourceGroupName
    - name: serviceName
      in: path
      value: $inputs.serviceName
    - name: apiId
      in: path
      value: $inputs.apiId
    requestBody:
      contentType: application/json
      payload:
        properties:
          description: $inputs.description
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      apiId: $response.body#/name
      apiResourceId: $response.body#/id
    onSuccess:
    - name: done
      type: end
  - stepId: createApi
    description: >-
      Create a new API with the supplied display name, path, and backend
      service URL when no matching API was found.
    operationId: Api_CreateOrUpdate
    parameters:
    - name: subscriptionId
      in: path
      value: $inputs.subscriptionId
    - name: resourceGroupName
      in: path
      value: $inputs.resourceGroupName
    - name: serviceName
      in: path
      value: $inputs.serviceName
    - name: apiId
      in: path
      value: $inputs.apiId
    requestBody:
      contentType: application/json
      payload:
        properties:
          displayName: $inputs.displayName
          description: $inputs.description
          serviceUrl: $inputs.serviceUrl
          path: $inputs.path
          protocols:
          - https
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      apiId: $response.body#/name
      apiResourceId: $response.body#/id
  outputs:
    apiResourceId: $steps.createApi.outputs.apiResourceId
    updatedApiResourceId: $steps.updateApi.outputs.apiResourceId