3

I need to expose an API endpoint in the html documents, so I can later do client-side rest calls (for search and/or subsequent pagination).

As the JS needs to stay agnostic of config files, I suppose that the <head> of the document with an appropriate <link> tag should be the go-to place. So something like:

<link rel="???" type="application/json" href="https://example.com/api" />

But what rel???

Looking through Mozilla docs and the Microformats' list, I found no obvious match.

Close candidates may be:

rel="alternate" - "Alternate representations of the current document" With the issue being that this is not a 'substitute version' for each document, rather a general resource. Feeds often use it like this, with all iterations pointing back to a single xml origin file or api, but I suppose that's not quite proper.

rel="search" - "Gives a link to a resource that can be used to search through the current document and its related pages." Almost makes sense for the current use case, but not quite so for a generic api endpoint (that may not even allow search at all).

rel="index" - "Refers to a document providing a list of topics with pointers that pertain to the current document." It could be argued that indeed an api holding the full resources may serve as an index for the parts actually displayed, especially with pagination as originally intended, but it seems a bit far-fetched and, again, it'd be rather particular to this use case.

Not so close candidates:

rel="https://example.com/api" - Not supported in any spec, only brief mention that Wordpress does it like this, with the rel="https://api.w.org/" random namespace. Does not validate.

rel="api" - Sounds fit and appropriate, thought i'd try it in a validator, no luck.

meta property="api" content="https://example.com/api" - Improperly use a meta for the link, with whatever name or property (OG/FB style) - does validate but is still just random repurposing.

So is there any standard or accepted practice for this?

Improve this question

1 Answer 1

Reset to default
3

We have tended to add API paths on an appropriate (to our applications) data- attribute on a suitable element close to the usage.

<input type="text" name="term"
       data-autocomplete-url="/api/ui/customapi/searchautocomplete?text={0}"
       value="" />

This can then be picked up by your JS and used as needed.

Improve this answer
5
  • Indeed, my next best option is something like this (custom attribute on the html element, would be even less obtrusive) but in that too is a bit of repurposing, meta tags in the head should be the proper way to do it if possible.
    – lucian
    Jan 21, 2022 at 15:48
  • Also, with search the suggested approach would be quite elegant – just put it on the input field. With pagination it wouldn't work that nice, unless the trigger is button driven and not self-loading / "infinite" scroll.
    – lucian
    Jan 21, 2022 at 16:32
  • That was just one example - we also have data attributes on the main html element, or on appropriate containing div elements as required. I disagree that meta tags are the "proper way to do it" - the list of allowed rel values is quite limited and none apply to your use case, whereas as the data-* attribute is flexible and available on every element to use as required.
    – Zhaph - Ben Duguid
    Jan 21, 2022 at 18:42
  • Supposedly 'the proper way' as per spec, indeed options are left scarce, I guess that's why WP did it their own way and, by the same token, why opengraph or schema had to add to or go around the spec. (might just as well put json in a script tag like schema does, I suppose). I'd steer clear of custom attributes, as their function is not that obvious for designers unfamiliar with the logic so they might more easily "get lost". I think I'll end up hooking to prefetch, since I use it anyway to help with the same functionalities... just trim the string a bit and that's it: a dual purpose rel
    – lucian
    Jan 21, 2022 at 20:57
  • @lucian Using prefetch may have unintended consequences - the browser "should preemptively fetch and cache the target resource" after the page is loaded. dns-prefetch or preconnect may be safer as that will only cause the browser to connect to the origin rather than request the whole link. With the data-* attributes you can be clear as to what the APIs are intended for (i.e. data-api-search, data-api-autocomplete, data-api-next, data-api-previous), otherwise I guess you can use the global id element to distinguish between the different links.
    – Zhaph - Ben Duguid
    Jan 23, 2022 at 14:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.