Announcing the Endpoint badge (beta)

[paulmelnikow]

Hi all, Shields has launched a beta features: the Endpoint badge.

What is the Endpoint badge?

The endpoint badge is a new kind of dynamic badge endpoint which renders a badge from a JSON endpoint.

What is it useful for?

1. Rapidly prototype new ideas and see the results on live badges before those features make it into Shields.
2. Handle use cases deemed too specific to include in Shields.
3. Implement things that Shields won't implement (e.g. for performance or stylistic reasons).

How does it work?

• Your endpoint returns static or dynamic JSON data in the Endpoint schema.
• Your user can override formatting via the query string.
• Shields take care of formatting, rendering, and caching.

Where can I host the JSON endpoint?

Literally anywhere that supports HTTPS.

• Tools like RunKit and Jupyter Kernel Gateway
• Any kind of JSON-returning cloud function
• Any server of your choosing
• Any static JSON file

Feedback

Your feedback on the new feature is much appreciated! Please feel free to comment in this issue with feedback or questions about how to use it. The #support room in Discord is also a great place to discuss it.

Known issues

• Fix formatting issues with the endpoint badge doc page #2837
• [endpoint] when logoSvg is specified the user cannot override the logo #2998

[chris48s]

Good work on shipping this 👍 I think this really opens the door to more of a "plugin" style architecture - users will be able to enjoy a wider range of more esoteric integrations and use-cases without us necessarily having to host a service integration in core for every single programming based service under the sun.

Sorry I didn't get a chance to raise this at the review stage, but one thing that I think is likely to be a point of confusion is the cache key. I think some users will try to set it to 0 and get unexpected results. It would be useful to more clearly communicate that there is a floor on the cache length (but as I remember it, its a bit fiddly to surface the value because the variable isn't set when we build the front-end). Is there a way we can more clearly communicate this in the docs?

[paulmelnikow]

Sorry I didn't get a chance to raise this at the review stage, but one thing that I think is likely to be a point of confusion is the cache key. I think some users will try to set it to 0 and get unexpected results. It would be useful to more clearly communicate that there is a floor on the cache length (but as I remember it, its a bit fiddly to surface the value because the variable isn't set when we build the front-end). Is there a way we can more clearly communicate this in the docs?

Yea, good shout.

The Endpoint service has its own floor of 300 seconds that's defined in the service, independent of anything that's configured at runtime. At least that's how I think it's implemented. (That work went on a while so TBH I don't completely remember.)

This is what I wrote in the docs:

I agree it's not totally clear; it doesn't mention the 300-second floor at all.

[RedSparr0w]

Nice work on this, I can definitely see this badge being used regularly.
👍

I tried using it before reading the docs or PR, just to see how easy/hard it would be to use.

And one of the things i found strange was that colorB is set using color, colorA using labelColor and logo using namedLogo or logoSvg.
Do you think it would be better to keep these matched to the query paramaters we currently use?

Also when an unknown key is included (such as colorB), the badge would result in:

I feel like it would make more sense to just ignore these keys?

Edit:
Some random badges using the endpoint badge:
(NZ time)



(doesn't show the json response if not requested by shields)
→← (wont show unless it is october)

[paulmelnikow]

And one of the things i found strange was that colorB is set using color, colorA using labelColor and logo using namedLogo or logoSvg.
Do you think it would be better to keep these matched to the query paramaters we currently use?

Ah yea, I agree it's a confusing for Shields users that the parameters aren't the same.

That said I think colorB is not really intuitive.color makes more sense.

I'd like to change the global query parameters to match what's being used here. We can continue to support the old options on the query string, probably forever, or implement something like #2340 to gently encourage people to switch over.

→← (wont show unless it is october)

Whoa, how'd you pull that off?!

Also when an unknown key is included (such as colorB), the badge would result in:

I feel like it would make more sense to just ignore these keys?

I think failing loudly is better because that way you know you have spelled something wrong. If it silently fails until you get it right it's harder to troubleshoot.

There is a showKeys flag we can pass to validate() which IIRC is used to return a detailed error message for query parameter validation. We could use that to return an error message which complains about the specific bad keys. I wonder if that would make for a better experience.

[chris48s]

I tried using it before reading the docs

Why not.. that's what most users will do :D

I'd like to change the global query parameters to match what's being used here. We can continue to support the old options on the query string

👍 I'd rather see us become more consistent by using labelColor and messageColor more widely and move towards colorA and colorB as legacy aliases.

[RedSparr0w]

→← (wont show unless it is october)

Whoa, how'd you pull that off?!

const output = {
  "schemaVersion": 1,
  "label": "", // can be empty
  "message": " ", // needs to atleast contain 1 char
  "color": "brightgreen", // could make this rgba(255,255,255,0) just incase
  "style": "flat", // should be flat/flat-square
  "logoSvg": "<svg xmlns=\"http://www.w3.org/2000/svg\"/>", // smallest valid svg
  "logoWidth": -15 // should bring the badge width to 0px
}

Although on iOS it shows up a little strange:

Edit: Chrome for reference:

I'd like to change the global query parameters to match what's being used here. We can continue to support the old options on the query string

+1 I'd rather see us become more consistent by using labelColor and messageColor more widely and move towards colorA and colorB as legacy aliases.

👍

I think failing loudly is better because that way you know you have spelled something wrong. If it silently fails until you get it right it's harder to troubleshoot.

There is a showKeys flag we can pass to validate() which IIRC is used to return a detailed error message for query parameter validation. We could use that to return an error message which complains about the specific bad keys. I wonder if that would make for a better experience.

Sweet, If that is an option then i'm +1 for that.

[niccokunzmann]

And one of the things i found strange was that colorB is set using color, colorA using labelColor and logo using namedLogo or logoSvg.
Do you think it would be better to keep these matched to the query paramaters we currently use?

• Announcing the Endpoint badge (beta) #2838 (comment)

Yes, definitely. It makes it easier for people implementing and endpoint or redirects to know what to include and what not. I.e. I have a short-URL which I can format like the badges URL: https://transifex.quelltext.eu/badge/<organization_slug>/project/<project_slug>/resource/<resource_slug>/<stat>.<extension>
This url redirects to the endpoint url. (https://transifex.quelltext.eu)

I feel like it would make more sense to just ignore these [invalid/unused] keys?
Hm. I think so, too.
I think failing loudly is better because that way you know you have spelled something wrong. If it silently fails until you get it right it's harder to troubleshoot.

We can have both: There are required fields. If they are not there, one can fail loudly. All other fields can be tested. That is, if the specification is fixed. But if the specification changes, it might be good to fail strictly, so people can get notified.

Another idea to think about:

Easy embedding of endpoint badges into shields.io

I provide the endpoint you mentioned:

https://transifex.quelltext.eu/badge/12-characters/project/12-characters-play/resource/07-better-to-be-hopeful-txt/translated.json
{
  "color": "#986700", 
  "label": "07-better-to-be-hopeful-txt", 
  "message": "41%", 
  "schemaVersion": 1
}

However, I would still like to give the users the ability in shields.io style, to customize the badge.
On my page, https://transifex.quelltext.eu/ you can see, that I fail.
So, having these endpoint badges, we only need something like badge meta data as JSON to include into the shields.io server. Nothing active - it is all the same.

[paulmelnikow]

It's awesome that you're using this! I hadn't considered the possibility that you'd want to redirect to the endpoint badge. Interesting!

It looks like the user overrides are working, e.g. your are redirecting

https://transifex.quelltext.eu/badge/12-characters/project/12-characters-play/translated.svg?style=for-the-badge&colorB=brightgreen

to

https://img.shields.io/badge/endpoint.svg?style=for-the-badge&colorB=brightgreen&url=https%3A%2F%2Ftransifex.quelltext.eu%2Fbadge%2F12-characters%2Fproject%2F12-characters-play%2Ftranslated.json

That's exactly correct. If the user happens to be specify some bad values, currently we're silently ignoring them, though if that behavior changes, it can be our responsibility to provide the user a helpful error message. Pointing users to the styles section on https://shields.io/ probably is the best thing you can do. Validating the parameters before the redirect wouldn't help.

[endel]

Hi @paulmelnikow, thanks for this feature, it's a really nice addition!

I've just open-sourced a Patreon endpoint: https://github.com/endel/shieldsio-patreon

Endpoint: https://shieldsio-patreon.herokuapp.com/endel
Image URL: https://img.shields.io/badge/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.herokuapp.com%2Fendel&style=for-the-badge
Preview:

[paulmelnikow]

Neat!

It's working right now. "Vendor unresponsive" appears after 30 seconds without a response, so probably your server is taking too long to respond.

Are you using a Free dyno on heroku? They go to sleep after a while, and after that do take a while to boot up.

[endel]

@paulmelnikow thanks a lot, I've edited my original post 😅 it was a silly mistake, forgot to use response.end() on Node.js 🙈

[paulmelnikow]

Aha! That sounds about right. Glad you got it working!

[paulmelnikow]

To keep the URLs concise, I'm thinking we should remove /badge from the endpoint URL. So /badge/endpoint.svg becomes /endpoint.svg.

Now that #2340 is merged we can add redirects without cluttering up our service implementations, so there would be little cost to providing backward compatibility.

[endel]

@paulmelnikow sounds good! let us know when you apply this change :)

[RedSparr0w]

If a logoSvg is specified at the endpoint, then the user cannot override which logo is shown (or not shown), Is this intended?

[paulmelnikow]

No, that sounds like a bug.

[RedSparr0w]

Cool, I've opened a new issue,

Also it may be good to figure out if we are going to support other formats (#2964) or not before #2838 (comment) is implemented, as that might change things.
Eg:
/endpoint/json.svg
/endpoint/yaml.svg
/endpoint/xml.svg
etc.

Edit: Although even if we do support other formats we could still have the base endpoint default to json.

[jcxldn]

I've setup a little demo website over here with a few more endpoint examples 😃

[paulmelnikow]

@endel and others following this thread: wanted to let you know that the URL change from https://img.shields.io/badge/endpoint.svg to https://img.shields.io/endpoint.svg has gone live.

If you update your URLs if will avoid a redirect, speeding up your badge slightly and avoiding making an unnecessary request to our server.

[Cherry]

Just found this thread and updated my endpoint at https://github.com/Cherry/shieldsio-steam-workshop. Thanks!

[paulmelnikow]

This feature seems to be stable. Feel like we may as well take this out of beta!