API Management API ID doesn't always contain the revision ID

[Berbe]

As indicated in comments, the API ID does not include the revision ID when the revision is current.

This is a problem when the returned ID is used to track an object's state, as an API ID without a revision ID doesn't reference a single object across time.
The terraform-provider-azurerm#12766 bug report sheds light on such a situation, which is hardly a Terraform problem, merely relying on the id contained in answers to GET queries on /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=<revision> resources.

For example, if a GET query on /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=1 returns:

{
  "id": "/subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example",
  "type": "Microsoft.ApiManagement/service/apis",
  "name": "example",
  "properties": {
    "displayName": "example",
    "apiRevision": "1",
    "description": "",
    "subscriptionRequired": true,
    "serviceUrl": "https://example.org",
    "path": "example",
    "protocols": [
      "https"
    ],
    "authenticationSettings": {
      "oAuth2": null,
      "openid": null
    },
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "apiRevisionDescription": "",
    "apiVersion": "",
    "apiVersionDescription": ""
  }
}

because revision 1 is current, the tracked ID will be revision-less.

If the current revision is then to be changed to 2, the object tracked by /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example will be revision 2 and not 1, breaking state tracking.

It would be best if revisions ID were always returned in answers' payload.

[ArcturusZhang]

Hi @Berbe thanks for this issue!

But I do not think it is correct behavior to let terraform to manage something that might be tempered by something else. You will get exactly the same situation if one of your terraform-managed resource get changed by some external sources - for instance you enlarged your os disk size of the VM managed by terraform, and run terraform apply again, it is for sure terraform will want to shrink your disk back - and the disk size cannot shrink therefore terraform will want to destroy your virtual machine and recreate.

And the ID you are showing in the description, that is the ID of the terraform resource, which should be different from the ARM Resource ID - an ARM resource ID cannot contain special symbols in it.
I believe the API management service is treating the revision number as a property of the one resource, by upgrading the revision, you just changed something on the existing one instead of create a new one (like the os disk size example above).
But I do not have enough service context to confirm this, therefore I am going to defer someone from the API management service team to explain more about this.

[ghost]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @miaojiang.

Issue Details

---

As indicated in comments, the API ID does not include the revision ID when the revision is current.

This is a problem when the returned ID is used to track an object's state, as an API ID without a revision ID doesn't reference a single object across time.
The terraform-provider-azurerm#12766 bug report sheds light on such a situation, which is hardly a Terraform problem, merely relying on the id contained in answers to GET queries on /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=<revision> resources.

For example, if a GET query on /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=1 returns:

{
  "id": "/subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example",
  "type": "Microsoft.ApiManagement/service/apis",
  "name": "example",
  "properties": {
    "displayName": "example",
    "apiRevision": "1",
    "description": "",
    "subscriptionRequired": true,
    "serviceUrl": "https://example.org",
    "path": "petshop3",
    "protocols": [
      "https"
    ],
    "authenticationSettings": {
      "oAuth2": null,
      "openid": null
    },
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "apiRevisionDescription": "",
    "apiVersion": "",
    "apiVersionDescription": ""
  }
}

because revision 1 is current, the tracked ID will be revision-less.

If the current revision is then to be changed to 2, the object tracked by /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example will be revision 2 and not 1, breaking state tracking.

It would be best if revisions ID were always returned in answers' payload.

Author:	Berbe
Assignees:	ArcturusZhang
Labels:	API Management, Mgmt, Service Attention, customer-reported, question
Milestone:	-

[Berbe]

But I do not think it is correct behavior to let terraform to manage something that might be tempered by something else.

This is out of scope of this issue: I did not specify the way the current revision changes, as this has no impact on this particular issue, which is how the API behaves/answers.

And the ID you are showing in the description, that is the ID of the terraform resource, which should be different from the ARM Resource ID [...]

All I am showing in the description are API queries and answers.
Terraform was merely there to explain the (reasonable) expectations on the the API and give a context as well as a use case to the issue. You can discard that part if you are uneasy with it.

an ARM resource ID cannot contain special symbols in it.

Let me try to explain again, showing you how responses differ between current and non-current revisions.

Revision 1 - current

Query to API:

GET /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=1?api-version=2019-12-01 HTTP/2
Host: management.azure.com
[...]

Response:

{
  "id": "/subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example",
  "type": "Microsoft.ApiManagement/service/apis",
  "name": "example",
  "properties": {
    "displayName": "example",
    "apiRevision": "1",
    "description": "",
    "subscriptionRequired": true,
    "serviceUrl": "https://example.org",
    "path": "example",
    "protocols": [
      "https"
    ],
    "authenticationSettings": {
      "oAuth2": null,
      "openid": null
    },
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "isCurrent": true,
    "apiRevisionDescription": "",
    "apiVersion": "",
    "apiVersionDescription": ""
  }
}

Revision 2 - not current

Query to API:

GET /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=2?api-version=2019-12-01 HTTP/2
Host: management.azure.com
[...]

Response:

{
  "id": "/subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=2",
  "type": "Microsoft.ApiManagement/service/apis",
  "name": "example;rev=2",
  "properties": {
    "displayName": "example",
    "apiRevision": "2",
    "description": "",
    "subscriptionRequired": true,
    "serviceUrl": "https://example.org",
    "path": "example",
    "protocols": [
      "https"
    ],
    "authenticationSettings": {
      "oAuth2": null,
      "openid": null
    },
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "apiRevisionDescription": "",
    "apiVersion": "",
    "apiVersionDescription": ""
  }
}

Revision 1 - not current

Query to API:

GET /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=1?api-version=2019-12-01 HTTP/2
Host: management.azure.com
[...]

Response:

{
  "id": "/subscriptions/a579fc6d-85fe-44a7-9ba6-8f08117c7237/resourceGroups/CA06AZGRGAPI001/providers/Microsoft.ApiManagement/service/CA06AZGAPIM001/apis/test-BR_ps;rev=1",
  "type": "Microsoft.ApiManagement/service/apis",
  "name": "example;rev=1",
  "properties": {
    "displayName": "example",
    "apiRevision": "1",
    "description": "",
    "subscriptionRequired": true,
    "serviceUrl": "https://example.org",
    "path": "example",
    "protocols": [
      "https"
    ],
    "authenticationSettings": {
      "oAuth2": null,
      "openid": null
    },
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "apiRevisionDescription": "",
    "apiVersion": "",
    "apiVersionDescription": ""
  }
}

Revision 2 - current

Query to API:

GET /subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example;rev=2?api-version=2019-12-01 HTTP/2
Host: management.azure.com
[...]

Response:

  "id": "/subscriptions/***/resourceGroups/example/providers/Microsoft.ApiManagement/service/example/apis/example",
  "type": "Microsoft.ApiManagement/service/apis",
  "name": "example",
  "properties": {
    "displayName": "example",
    "apiRevision": "2",
    "description": "",
    "subscriptionRequired": true,
    "serviceUrl": "https://example.org",
    "path": "example",
    "protocols": [
      "https"
    ],
    "authenticationSettings": {
      "oAuth2": null,
      "openid": null
    },
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "isCurrent": true,
    "apiRevisionDescription": "",
    "apiVersion": "",
    "apiVersionDescription": ""
  }
}

I believe the API management service is treating the revision number as a property of the one resource, by upgrading the revision, you just changed something on the existing one instead of create a new one (like the os disk size example above).

The problem here is that by querying a specific revision of an API resource (as seen in the requests above), if the queried revision is current, the id field of the answer object won't contain the revision number.
This id field of that answer object shall be able to be relied upon to track a specific object, ie a specific revision of an API resource.

In other words, with the same request made to the same specific revision, this id changes depending on the context.
The id field of the response object is the problem here. This is an API/SDK problem.

But I do not have enough service context to confirm this, therefore I am going to defer someone from the API management service team to explain more about this.

Going through case support with M$ is a nightmare already. So far, support from technical people on GitHub issues was satisfactory.
Please avoid speculation and try to reproduce what I am showing here on your end if that might help you grasp the problem at hand. I remain at your disposal if your need details/specifics.

[tadelesh]

We have retired support for Azure SDK for Golang libraries which do not conform to our current Azure SDK guidelines (see announcement). Please migrate to the latest version according to the migration guide. If you could still repo this problem, please submit a support ticket in Azure directly.