Just to summarise this a bit
Example valid API call: https://api.sdkman.io/2/candidates/default/scala
Example invalid API call: https://api.sdkman.io/2/candidates/default/does-not-exist

While this doesn't appear to be a publicly documented API, we do have one of the project maintainers suggesting its use in sdkman/sdkman-cli#1045

Thanks for your feedback @chris48s . The approach is being reviewed on the sdkman side

While this project does certainly fall into the category of the types of developer/technologist-centric service and has some good adoption and traction, I was also wondering about the documentation.

One of the things we've called out explicitly in our guidelines for new badges is:

Badges should not obtain data from undocumented or reverse-engineered API endpoints.

Due to issues we've had in the past. I think this would be a reasonable badge to include, but I'd really like to see the documentation formalized a bit first. FWIW something as simple as a hosted swagger page has been sufficient in many prior cases

Due to issues we've had in the past. I think this would be a reasonable badge to include, but I'd really like to see the documentation formalized a bit first.

Sure 🙏

FWIW something as simple as a hosted swagger page has been sufficient in many prior cases

❤️

✄1�7 Commented accordingly on the SDKMAN! side

cf sdkman/sdkman-cli#1045 (comment) :

Thanks for facilitating the cross-thread comms @adriens!

I confess I'm a little torn on whether we should proceed with the API in its current state or wait till it's more official. Curious what others think

The reason we added the line

Badges should not obtain data from undocumented or reverse-engineered API endpoints.

was because we had some situations where a contributor worked out that a project had an API by inspecting the frontend code for their website or whatever, added a badge that calls it, and then we ended up relying on an API that wasn't really intended for public use. This then either annoyed the maintainers of the company/project behind it or we had no reasonable expectation of stability/compatibility over time (because devs maintaining the the API were making the assumption the only thing consuming it was their own frontend code) and stuff kept breaking.

I'm less worried about someone adding a badge that calls this API if the maintainers of the project are actively suggesting we use it for this purpose, even if it lacks formal docs.

Yeah that sounds fair to me. I think as a related, but separate, followup it'd be worth considering augmenting the text with a clause to that effect

@adriens - we've got a great tutorial on adding new badges in case you or anyone else is interested in working on it!

@calebcartwright :

we should proceed with the API in its current state or wait till it's more official

i guess the "wait till it's more official" is the most appropriated option 🤔

@adriens - we're actually saying the opposite, and that we're fine with proceeding now given what the SDMAN maintainers have indicated

WOW, that sounds great 👏