Gravatar for ssartell@rightpoint.com

Question by ssartell, Oct 13, 2016 10:34 AM

REST API URI hell

Why are there so many URIs coming back from the REST API? Each result has ClickUri, PrintableUri, Uri, clickUri (lowercase), printableUri (lowercase), uri, raw.clickableuri, raw.printableuri, raw.sysclickableuri, raw.sysuri, and raw.uri. Lowercase clickUri seems to be the true URI based on CoveoJsSearch.js source and ResolveResultClickableUriProcessor, but can I get some clarification on what the rest of them are and why there are so many? Thanks!

1 Reply
Gravatar for mlaporte@coveo.com

Answer by Martin Laporte, Oct 13, 2016 11:24 AM

Quite a few things (but I admit this is overwhelming):

  1. On some systems, the URI that uniquely identifies an item is different than the one that can be used to "open" it. For example, in Outlook 365 you cannot open an attachment directly (I think), so the clickUri for those is the one that opens the email containing the attachment.
  2. Then, on some systems the "real" URI is extremely ugly. For example, on an exchange server it's a huge GUID - not very helpful for the end user. For those we generate a human-friendly URI that should only be used for display purposes (printableUri).
  3. The fields with the leading uppercase are an artefact from the past, and they are gone in an upcoming version of the API. But we can't start using this version in JS UI without introducing a breaking change (because some implementations are referencing them), so we're waiting for a major version update of the framework to do so.
  4. In the same fashion, the field names with the sys prefix are gone in the new version of our Cloud platform, but the V2 version of the REST API still emulates them to allow a seamless transition of older deployments. Again, when the JS UI switches to the new "V3" version (not available yet) those will be gone too.
  5. Then finally, the fact that some important fields are repeated at the top level and under raw is something we'll probably drop too in the V3 API.

So, the plan is to have only the required uri, clickUri and printableUri in the end.

Gravatar for ssartell@rightpoint.com

Comment by ssartell, Oct 13, 2016 12:17 PM

Ah, thanks for the info. So clickUri is the way to go as far as rendering links with Coveo for Sitecore?

Gravatar for jflheureux@coveo.com

Comment by Jean-François L'Heureux, Oct 13, 2016 12:59 PM

With Coveo for Sitecore, using the Coveo JavaScript Search Framework, you should always use the [ResultLink component](https://coveo.github.io/search-ui/components/resultlink.html).

This component uses the `result.clickUri` property to generate the proper HTML for the link and includes the result title as the link text.

It is important to at least use the `CoveoResultLink` CSS class on your link in order for the Coveo JavaScript Search Framework to bind the Coveo Usage Analytics event handler on your links to notify the service that the user have clicked on the result. If you fail to do that, you won't be able to use Coveo Machine Learning to improve the relevancy of your search results and won't have complete analytics information to identify successful visits that ended with the visitor finding what he was looking for.

Gravatar for ssartell@rightpoint.com

Comment by ssartell, Oct 13, 2016 4:29 PM

Well that's good to know. Are there any other benefits to the CoveoResultLink component? Typically I haven't used that component because the title field might not be what we want to display. Like we might want to link a whole div instead of just some text. Is there documentation about ensuring analytics/machine learning works correctly?

Gravatar for jflheureux@coveo.com

Comment by Jean-François L'Heureux, Oct 14, 2016 1:56 PM

If you need to change the title or content of the ResultLinlk component, just add something between the opening and closing tags:

<a class='CoveoResultLink'><div>content of your DIV</div></a>
Gravatar for jflheureux@coveo.com

Comment by Jean-François L'Heureux, Oct 14, 2016 1:57 PM

You asked:

Is there documentation about ensuring analytics/machine learning works correctly?

I don't think there is at the moment.

Ask a question