Allow embedding endpoint badges into the frontend

[niccokunzmann]

Motivation

The endpoint badge #2838 allows implementing the api-to-badge conversion logic in different locations without need to modify or add shields.io services. This leads to a possible diversification and emergence of new badges, which should be faster than badges added directly to shields.io source.

Context

In order to provide an endpoint badge, one "only" needs to create an API as specified in https://shields.io/#/endpoint.
However, to make this badge usable by other people, one as developer would like to provide the same template functionality as shields.io does, such as https://img.shields.io/appveyor/ci/:user/:repo.svg when you click on a badge at https://shields.io
Example: http://transifex.quelltext.eu/

Problem

Each new endpoint wants to provide configurable badges.
Currently, the endpoint badge only allows using your endpoint.
Configuration needs to be done manually by users or as crappy as on https://transifex.quelltext.eu

Possible Solution

A possible solution to this would be

• A way of including endpoint badges into the shields.io frontend.
  • using multiple URLs for services in case of some going down (using just the first one is sufficient)
  • a reference to the endpoint's repository can be included so that we can track if something goes wrong and other people can do a set-up if needed.
  • customization of the endpoint's url (not the shields url using ?url=...) in the frontend
  • adding all this information as JSON, no coding required.
• A documentation of how to achieve this
  • located in https://shields.io/#/endpoint or /docs?

Relevance

As stated earlier, I believe that in the future, more badges will exist using the endpoint API than the shields.io implementation. As such, it would be good, if shields.io is still the place to go to find these badges, sparing the badge users the hassle of different template engines.

Related:

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

[paulmelnikow]

Hi! That's a nice suggestion. I think we'd handle this like any other badge proposal. Since the upstream API uses the Shields.io format, the implementation is easier and could reuse existing code.

1. Would you like us to add one for Transifex? There's been interest: Badge request: Transifex #497. I'm happy to do a PR if you'd like.
2. We could add on the endpoint page some documentation describing the process of getting a badge included, and maybe point to an example PR.
3. It could also be cool to have an embeddable front-end component that allows a service provider to provide a badge popup-like interface in their website, which allows users to set customization options and get a badge URL.

[niccokunzmann]

(1) Would you like us to add one for Transifex? There's been interest: #497. I'm happy to do a PR if you'd like.

We can add one for Transifex, yes. If you like, you can do it. I can do it, too. I think, it would be located in the endpoint directory, shouldn't it? Or not? Should it be a different service directory? Probably yes, because the sorting of the services is based on the topic and not on the implementation - although the API is probably the same if the topic ("Docker", "Transifex") is the same.

(2) Yes!
(3) I think this would be a new issue and not the scope of this one.

[paulmelnikow]

There's a bunch of helper code that needs to be moved / extracted, so I'm happy to take this one.

Should it be a different service directory? Probably yes, because the sorting of the services is based on the topic and not on the implementation - although the API is probably the same if the topic ("Docker", "Transifex") is the same.

Yup, exactly, it would belong in services/transifex.

[niccokunzmann]

Okay, you are welcome to do so. I can review if you like. Would you solve this issue and #497 at the same time?

What I would like to see is:

• using multiple URLs for services in case of some going down (using just the first one is sufficient)
• a reference to the endpoint's repository can be included so that we can track if something goes wrong and other people can do a set-up if needed.
• customization of the endpoint's url (not the shields url using ?url=...) in the frontend
• adding all this information as JSON, no coding required.

Edit: added these points to the issue description.

[paulmelnikow]

I'm proposing we add a Transifex badge which would appear in our normal badge listing.

I feel like this is asking for something a bit different, which we could also do, which is provide a page where a user can paste in an endpoint badge URL and then customize it.

• using multiple URLs for services in case of some going down (using just the first one is sufficient)

AFAIK we don't have any services that do this now.

[niccokunzmann]

I feel like this is asking for something a bit different, which we could also do, which is provide a page where a user can paste in an endpoint badge URL and then customize it.

I understand why it is not possible to do it 100% as I proposed: endpoints may have a different format from the one shields.io uses. Thus, it probably needs some programming to map the one format to the other.
i.e. shields: /transifex/:organization/:project whereas the service may use endpoint.json?org=:organization&p):project. It would not make sense to break from consistency for that. So, yep 👍, I agree.

[paulmelnikow]

I know this isn't exactly what you asked for, though I think it's a nice touch to provide a customization UI you can use for live testing: http://shields-staging-pr-2908.herokuapp.com/#/endpoint

I'm working on the Transifex badge now.

[paulmelnikow]

I finished the refactor to make it easy to pipe through badge data that's using the endpoint format. There are some formatting changes I'd like to make to bring things in line with the other Shields badges. Would you like to make some changes to your badges to implement some formatting changes? Or, would you prefer that any re-formatting is done in Shields?

[niccokunzmann]

Would you like to make some changes to your badges to implement some formatting changes? Or, would you prefer that any re-formatting is done in Shields?

I would say:

• there can be a clear documented way of how to make an endpoint badge which needs not formatting
• there must be an option for shields to do the formatting
• I will not change my format as I would need to change code where my badges are located.