Use category name as label and id as query parameter

[holly-cummins]

As requested by @cescoffier. Resolves #1836

The front-end almost already had logic for distinct values and labels in the dropdown filters, it just needed a few things stitching together. I've added a new record on the backend and a new interface on the front end, to capture the fact that categories have both a name and an id.

This changes the drop-down to use the extension label, while using the value in the query string. It's a slightly breaking change because some urls, like AI, change, from https://code.quarkus.io/?extension-search=category:artificial-intelligence to http://localhost:8080/?extension-search=category:ai. However, as the url being used is now aligned with the platform categories, I think that's ok.

I had a dilemma about whether to use the name or id in the aria label, now they're distinct. I went for the id, since it's more concise and what the tests expect.

Before:

After:

[ia3andy]

that might break external services using the api 😔

[ia3andy]

could add a new field categoryTitle? not optimal but backward compat?

[ia3andy]

☝

[holly-cummins]

could add a new field categoryTitle? not optimal but backward compat?

It would have to be categoryKey. What's currently being used in the url is a slugified title, but the key is a more natural fit for the url (since it's already slug-compatible without any mapping). So my change is switching it from using the quasi-title to key.

I can't decide whether it's better to try and maintain two different query parameters going forward, or to accept the one-time break in the query parameters in the interests of simplicity. It only affects one or two categories, like ai.

I don't know how many consumers of the API there are. The extensions site uses the API, but it doesn't use the category parameter. And actually, if there were other consumers of the API, they'd probably already be broken, because nothing else in the quarkus-ecosystem uses that same mapping for quasi-titles. I think consumers of the API would already expect to pass in the category key.

So we could use categoryKey for the query parameter, which has the advantage of being explicit, and the disadvantage of being longer. And we could continue to honour category as an input parameter, but it means keeping a lot of code around to support a behaviour that it's extremely unlikely anyone is relying on. I think they'd only be using a category=artificial-intelligence search if they'd copy-pasted it from the current code.quarkus.io toolbar, and I did a search for https://github.com/search?q=org%3Aquarkusio+%22category%3D%22+%22artificial-intelligence%22&type=code, and couldn't find any usages.

[holly-cummins]

Oops, it's called id, not key. So my suggestion is for categoryId, not categoryKey. But honestly, I don't think it's worth leaving in all that code it to support the existing unexpected behaviour for one or two categories.

[ia3andy]

There are many consumers including IDEs plugins

[cescoffier]

Was the "API" documented somewhere? If not, we can break it; it's a private API. If any tools rely on this, we need to work toward making it public (with clear expectations and a contract.... and tests)

If it was documented, we need to go through a deprecation cycle: support both for a bit and add a warning in the public API.

[ia3andy]

https://code.quarkus.io/q/swagger-ui/

[holly-cummins]

https://code.quarkus.io/q/swagger-ui/

I don't see any reference in there to the mapping of the category string from what's in the registry and extension metadata. Actually, I can't see category query parameter listed in there at all. Can you paste in the exact line, @ia3andy? I searched for "category" but couldn't find it on the swagger page.

The case we're trying to cover is someone who says "I want to query code.quarkus.io by category, but I don't want to use the category strings that are defined in the registry, and I don't want to use the category strings that are in extensions' metadata. And it's artificial intelligence that I want to query." It just seems like quite a niche use case to me, doesn't it?

[cescoffier]

How is the swagger generated? Is it a statically generated one, and do we check our compliance? If this is runtime generated, without any compatibility guarantees, I would not consider that as a public API contract.