shields
shields copied to clipboard
badges
Badge request: SDKMAN
:clipboard: Description
This badge is dedicated to SDKMAN! so people can share that :
- 1️⃣ Their software is distributed through
sdk - 2️⃣ The latest version of the released software
A clear and concise description of the new badge.
- Which service is this badge for e.g: GitHub, Travis CI : SDKMAN!
- What sort of information should this badge show? : current version
📷 Static example
https://img.shields.io/badge/SDKMAN!-16.16.11-blue
:link: Data
Where can we get the data from?
- Is there a public API? Yes
- Does the API requires an API key? Nope
- Link to the API documentation. here
:microphone: Motivation
On software homepage, it would help people know that :
- 1️⃣ Core software is distributed through SDKMAN!... which makes things very easy
- 2️⃣ The target available version
⚡ Specific use case?
Embed shield :
- 1️⃣ On GH README homepage
- 2️⃣ On official sdks list
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 https://github.com/sdkman/sdkman-cli/issues/1045
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
❤️
cf https://github.com/sdkman/sdkman-cli/issues/1045#issuecomment-1033663080 :
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