Enable deep links to API versions and operations

[ZarTrox]

Bug description

When you share a link to an API-operation with colleagues/Partners those cannot immediately access the API. Instead after sign-in they are directed to an empty API details page. To see the API, one has to search the API-details page for the API and it's operation or re-enter the Link. Either way a working deep link to an API version would facilitate communication.

Reproduction steps

1. Open URL of an API version in an incognito window of your browser
2. After sign-in the empty API details page is displayed with no content

Expected behavior

A working deep link. The same as already possible with normal pages.

Is your portal managed or self-hosted?

Managed

[azaslonov]

Hi @ZarTrox, actually you can use deep-linking, just like this:
/api-details#api=echo-api&operation=600592153af4ef2b245bae53

and, in case of sign-in, you can use returnUrl parameter (with URL-encoded value), so you that the link would look like this:
/signin?returnUrl=%2Fapi-details%23api%3Decho-api%26operation%3D600592153af4ef2b245bae53

Hope that helps. Please feel free to re-open this issue or shoot me an email, if you need further assistance.

[AnRei123]

Hi, thank you for showing me how I can make of deep-linking even for APIs in the portal by encoding the URL value even in case of signing in!
But I like to ask you to reopen this ticket. For our notification service this approach helps us to solve the issue. But, we also like to easily like to exchange links to operation details (incl. sign-in) by just copying the URL from the address bar from the API details page and pasting it without requiring further manual transformation and efforts to any required target such as an e-mail or an MS Teams chat on the fly. Could you therefore reopen the ticket and support checking if the URL needs to be encoded and redirected as part of the Sign-in process based on a given deep link?

[AnRei123]

As developer like to easily copy the URLs for any operation details page and reference it in any document such as a wiki page, I like to request again that deep links to the operation details are supported with the URL that is displayed for the operation details page in the browsers address bar or to provide a button widget for the operation details page that allows to copy the URL as a deep link.
Please reopen the ticket again.

[benohead]

Basically, the direct deep link https://<developer-portal-url>/api-gallery/details#api=<api-id>&operation=<operation-id> doesn't work if users need to sign in.

The user is redirected to https://<developer-portal-url>/signin?returnUrl=/api-gallery/details#api=<api-id>&operation=<operation-id> instead of https://<developer-portal-url>/signin?returnUrl=%2Fapi-gallery%2Fdetails%23api%3D<api-id>%26operation%3D<operation-id> (so with a properly encoded return URI).

So the returnUrl is effectively /api-gallery/details (since everything after the # is considered to be a fragment for the /signin page) and you land nowhere after signing in.

It does look an error in redirection login which should properly URL encode the return URI.

And of course, you can directly link to the /signin URL with the corresponding encoded returnUrl but this means that the user will be presented the sign in page every time he follows such a link, no matter whether he's already logged in or not, which is not nice either.

[AnRei123]

If the user has been already logged in to the referenced portal environment, the encoded deep link is also not working. Please provide a proper redirect mechanism for both cases. Copying and referencing the URL should properly work for all DevPortal pages without further encoding activities of the users.

[azaslonov]

I could repro it for the case with "Require sign-in" option enabled, but regular deep linking works as expected. @AnRei123, can you please give an example of such deep link (maybe without hostname)?

[AnRei123]

Here an example:
https://.com/signin?returnUrl=%2Fapi-gallery%2Fdetails%23api%3Dcore-base-api-form-v3

[azaslonov]

@AnRei123, that is because you're sending the signed-in user to the sign-in page. Instead, you should give them a deep-link like this:
https://contoso.com/api-details#api=httpbin-org&operation=get

[dhall19]

We are also seeing this issue, our use case is that we host a site that contains deep links to APIs which look like this:

<a href="https://ourportalpage.com/api-details#api=anApp" target="_blank" >

However while this URL works when we paste it into a browser tab, when a user clicks on the link on our site they are redirected to the sign-in page even if they are already signed in, and as mentioned by @benohead when they do sign in they are not redirected to the API page.

Is there anything else we should be doing to get these links to work?