Jetbrains Badge uses old deprecated API that only supports IDEA plugins

[frimtec]

Are you experiencing an issue with...

• shields.io
• My own instance
• badge-maker NPM package

🪲 Description

The implementation to generate Jetbrains badges (https://github.com/badges/shields/blob/master/services/jetbrains/jetbrains-base.js) usees an old deprecated API that only works for IDEA plugins but not for other jetbrains plugins (e.g. TeamCity).
See also Ticket at Jetbrains YouTrack: https://youtrack.jetbrains.com/issue/MP-3341

The new API is https://plugins.jetbrains.com/api/plugins/<PLUGIN-ID> and supports all plugins in the Jetbrains marketplace.

Works - as long as the deprecated API is operationl (IDEA-Plugin):
🔗 https://img.shields.io/jetbrains/plugin/v/15308-import-control

Does not work (TeamCity-Plugin):
🔗 https://img.shields.io/jetbrains/plugin/v/12382-inspection-violation-notification

[frimtec]

The new API can be used to retrieve total downloads as well as the current version.
Examples:
🔗 https://plugins.jetbrains.com/api/plugins/12382 (use for number of downloads)
🔗 https://plugins.jetbrains.com/api/plugins/12382/updates (use for version)
🔗 https://plugins.jetbrains.com/api/plugins/12382/rating (use for rating)

[calebcartwright]

Thanks for the report @frimtec and providing the additional info on the new endpoint! By any chance do you know when JetBrains may be planning to drop the old API that we're currently using? We'd certainly like to make to switch since the new API supports additional plugin types, but would be good to know when the old one will be shutdown as well.

[calebcartwright]

@chris48s - My inclination was to label this as a service badge improvement since IIUC we're really just updating the service classes to leverage a new API. Not that the bug v. service badge labels matter all that much but wanted to get your thoughts since the bug label was added

[frimtec]

@calebcartwright - I guess there is no shutdown date defined yet.
From my ticket about the not supported plugins for TeamCIty (https://youtrack.jetbrains.com/issue/MP-3341) I got the following statement:

This is expected behaviour because this API was designed to work for IntelliJ plugins only. 
By the way this API is deprecated and would be removed in the future.

[chris48s]

If you are a user who doesn't know about the implementation details, here's what you see:

• Shields has a "Jetbrains plugin version" badge
• 15308 and 12382 are both valid jetbrains plugin IDs
• https://img.shields.io/jetbrains/plugin/v/15308 works but https://img.shields.io/jetbrains/plugin/v/12382 doesn't

That looks like a bug to me, but you could frame "support more jetbrains plugin IDs" as a feature request if you prefer. I agree it is somewhat ambiguous.

Labels aside, my initial assumption was that we could fix this in place and just drop in the new API as a replacement for the old one but looking into it a bit further, it looks like the newer API isn't quite compatible with the old one.

If we've got a numeric plugin ID, all is well:
https://plugins.jetbrains.com/plugins/list?pluginId=1347
https://plugins.jetbrains.com/api/plugins/1347

but with the old API, it was possible to call something like
https://plugins.jetbrains.com/plugins/list?pluginId=org.intellij.scala
whereas
https://plugins.jetbrains.com/api/plugins/org.intellij.scala
is not a valid call on the new API.

It looks like in order to switch to the new API we would need to break some existing badges that use the https://img.shields.io/jetbrains/plugin/v/org.intellij.scala format, unless there is another query/endpoint we can use? Maybe that is unavoidable if the old API will be removed at some point. Are there any docs for this API? The only ones I can find tell you to use the "old" one: https://plugins.jetbrains.com/docs/marketplace/plugin-details.html

[calebcartwright]

That looks like a bug to me, but you could frame "support more jetbrains plugin IDs" as a feature request if you prefer. I agree it is somewhat ambiguous.

Ah, that's the important distinction. I was (incorrectly) under the impression that the TeamCity plugins were a new thing. Bit surprised this hasn't come up before

unless there is another query/endpoint we can use? Maybe that is unavoidable if the old API will be removed at some point

We could add a new route for the TeamCity plugins, at least as a tactical option to enable support for those without breaking existing badges, and add redirectors as necessary down the road

[frimtec]

The old API worked for Intellij-IDEA plugins only. The new API supports all plugins on the "Jetbrains Marketplace".
It is correct that the new API is not compatible with the old one. Only the numeric plugin ID can be used as key.

To not break old badges, would it be an idea to create a new "badge-type" for jetbrains-marketplace, supporting all existing plugins and keep the old one unchanged (restricted for intellij-Idea plugins as of now - at least as long as the old API is operational)?

I have not found a documentation either for the new API, but Jetbrains just created a ticket to document, that the old API is deprecated (:link: https://youtrack.jetbrains.com/issue/MP-3342).

[chris48s]

I think the approach we should take is:

• Keep the existing badge URLs under /jetbrains . If we make a new badge, we're just going to end up doing this with redirects later
• If the request is like https://img.shields.io/jetbrains/plugin/v/12345 we call https://plugins.jetbrains.com/api/plugins/12345
• If the request is like https://img.shields.io/jetbrains/plugin/v/12345-some-text we call https://plugins.jetbrains.com/api/plugins/12345
• If the request is like https://img.shields.io/jetbrains/plugin/v/some.text we call https://plugins.jetbrains.com/plugins/list?pluginId=some.text for as long as it works and then we change it to throw an error when it eventually goes away
• Remove the examples in the front end that use the https://img.shields.io/jetbrains/plugin/v/some.text style now so we stop "promoting" that form of the badge URL given we know it will go away at some point.
• Pinned issue/tweet/etc when they stop working

[frimtec]

Many thanks for the fix :-)