[Announcement] 📢📢📢Move xref.docs.microsoft.com to a new endpoint

[yufeih]

With the move to https://learn.microsoft.com and for a more unified API integration experience, Microsoft Learn Engineering team is moving the https://xref.docs.microsoft.com endpoint to the new https://learn.microsoft.com/api/xref endpoint and planning on retire the xref.docs.microsoft.com domain at the end of this calendar year.

The new https://learn.microsoft.com/api/xref endpoint is effectively available from now and will receive the same SLA and support as the https://xref.docs.microsoft.com endpoint. This is an example query from both endpoints:

• new: https://learn.microsoft.com/api/xref/query?uid=System.String
• old: https://xref.docs.microsoft.com/query?uid=System.String

The old xref.docs.microsoft.com domain will still be supported until the end of this calendar year, giving users time to migrate to the new endpoint:

• If you explicitly set the xrefService property to https://xref.docs.microsoft.com/query?uid={uid}, change the value to https://learn.microsoft.com/api/xref/query?uid={uid}.
• If you depend on the https://xref.docs.microsoft.com endpoint for other reasons, change the base URL to https://learn.microsoft.com/api/xref.

This move does not retire the docs.microsoft.com domain, which would still be supported and be redirected to learn.microsoft.com.
This move does not change any functionality of the xref service, the API surface area would remain the same.

[KalleOlaviNiemitalo]

Are the endpoint and the SLA going to be documented at https://learn.microsoft.com/en-us/training/support/integrations?

It isn't really "training", but I don't see where else learn.microsoft.com APIs are documented.

[yufeih]

No. With #8595 docfx now does not depend on the xref service to resolve BCL types. Deprecated APIs are not documented on MS learn. We still keep the xref service endpoint at the moment for people not updated to the latest version of docfx and uses the endpoint directly for other purposes.

[gfraiteur]

Is there any new restriction to use this service? I am intermittently getting "access denied" when building our doc (Metalama).

[glopesdev]

@gfraiteur @yufeih same here, unable to build docs with either old or new xrefService due to 403 access denied.

[gfraiteur]

We figured out that the 403 seems to be caused by a throttling mechanism. When this happens, the whole office is losing access to the whole learn.microsoft.com for a few minutes. Needless to say, this is highly annoying, and our online doc no longer has completely resolved XRefs.

[glopesdev]

@gfraiteur thanks for the quick reply, I tried changing my IP and indeed this solved the issue, so it seems like a throttling mechanism is indeed in place.

[filzrev]

The old xref.docs.microsoft.com domain will still be supported until the end of this calendar year, giving users time to migrate to the new endpoint:

Support for xref.docs.microsoft.com is scheduled to end of this month.
But it seems that a lot of docfx users are using docfx v2.59.4 and not updating xrefService URL.

• "xref.docs.microsoft.com" NOT is:fork
• "xref.docs.microsoft.com" org:microsoft
• "xref.docs.microsoft.com" org:dotnet

Is this endpoint stopped according to schedule that described above?

[mikeebowen]

With the move to https://learn.microsoft.com and for a more unified API integration experience, Microsoft Learn Engineering team is moving the https://xref.docs.microsoft.com endpoint to the new https://learn.microsoft.com/api/xref endpoint and planning on retire the xref.docs.microsoft.com domain at the end of this calendar year.

The new https://learn.microsoft.com/api/xref endpoint is effectively available from now and will receive the same SLA and support as the https://xref.docs.microsoft.com endpoint. This is an example query from both endpoints:

• new: https://learn.microsoft.com/api/xref/query?uid=System.String
• old: https://xref.docs.microsoft.com/query?uid=System.String

The old xref.docs.microsoft.com domain will still be supported until the end of this calendar year, giving users time to migrate to the new endpoint:

• If you explicitly set the xrefService property to https://xref.docs.microsoft.com/query?uid={uid}, change the value to https://learn.microsoft.com/api/xref/query?uid={uid}.
• If you depend on the https://xref.docs.microsoft.com endpoint for other reasons, change the base URL to https://learn.microsoft.com/api/xref.

This move does not retire the docs.microsoft.com domain, which would still be supported and be redirected to learn.microsoft.com. This move does not change any functionality of the xref service, the API surface area would remain the same.

The links in your post get 404.

[gfraiteur]

It seems that https://learn.microsoft.com/api/xref/ does not solve the problem we are having: being victim to an IP-based usage threshold. When we compile our documentation, after a few seconds, the whole IP gets an Access Denied error on the whole https://learn.microsoft.com domain. We have to wait a couple of minutes before getting access back. It's not possible to compile our documentation in these conditions.

[filzrev]

xrefService endpoint is retired as announced at #9659
And xrefService option is no longer supported on latest version of docfx.

When using older version of docfx or using xref link inside conceptual document.
It need to set xref option instead.
https://dotnet.github.io/docfx/docs/links-and-cross-references.html#cross-reference-to-net-basic-class-library