This is a custom shields.io badge I use on my website via the shields.io json endpoint, It shows the server count for my bot. It uses Cloudflare workers as a backend to refresh itself every five minutes with up to date information. Though the same thing can be done without any code or cloudflare integrations.
Shields.io is a service that provides free badge images which show information about accounts or apps. They support a wide variety of services like Github, Discord, Twitter, and more. But in some situations they may not have the exact badge you want if you’re using a service that’s less well known, or your own application.
Shield badges are free, and can give a very professional impression for your site. These are ideal for free hosted sites for discord bots. They do not increase any load on your site or take up any space. You can also customize the style to suit the badge to your site.
Note : In this article I reference my bot site having a badge. It has since been redesigned but the endpoint is still active. See the badge below.
What does the JSON endpoint need?
The shields.io JSON endpoint page specifies that it expects a JSON response with three required fields. There is the schemaVersion which is just a technical element, it’s always set to 1. It also requires a label (which goes on the left of the badge), and the message (which goes on the right). There is recommended fields like color which will set the color for the badge, or cacheSeconds which specifies how long the data should be cached for by shields.io. Depending on which solution you use, you may need to set the cacheSeconds higher or lower, more on this later.
So how do you create a JSON endpoint easily? There’s two easy ways, Integromat and Cloudflare workers. Integromat is an integration service, and is designed to work easily with no knowledge of code. Cloudflare workers require coding and debugging knowledge.
Which one should you choose?
The drawback to Integromat is that the free subscription will only allow you a limited amount of requests a month (around 500 a month depending on what your badge is), which isn’t good if you want a badge that is frequently updated. To put it into perspective, a badge that updates every five minutes would take 288 requests a day. My server counter used to update every 12 hours using this method, using 60 requests a month, leaving over 400 for anything else I needed.
Cloudflare workers allow much more requests, up to 100,000 a day! But require a good knowledge of coding and how to debug the code. Cloudflare workers are written in JavaScript, and have much more flexibility than Integromat badges. CloudFlare also measures in execution time and requests over actions, meaning you can do more in Cloudflare. Provided you have a fast script.
If you need to show data that doesn’t change often or doesn’t require many requests, Integromat is probably the best option. If you need to show data that changes often or need to perform calculations, Cloudflare is the probably the best option. Just remember that you have limits on how much you can do. (It says scripts only allow 10ms to complete but the scripts are fast and usually take less than 1ms according to Cloudflare)
What do you need to start?
Assuming you’ve chosen from the two options above, you’ll need a reliable data source you can get the data from that you want to show. The best method would be to look for an JSON or XML API linked to what you are trying to get, because both Integromat and Cloudflare workers can easily support those. If there is no API, you may want to consider looking at an alternative source of information. APIs that require authentication in the headers are also usable, though slightly more complex.
For this example I’ll use the discordbotlist.com API, it’s a JSON API that doesn’t require any authentication and works from GET requests.
I’ll explain how to set this up in Integromat first.
Set up badges without code (Integromat)
Sign up for an account if you don’t have one (you can just sign in with Github or google). You can sign up to a free account which will allow you to make around 500 requests a month. This depends on how complex your badge is.
Create a scenario and a webhook. This will allow the webhook to execute a set procedure when it’s executed. Which will be getting the data and returning it in a JSON format that shields.io can understand. This guide will help with creating webhooks, for the data structure you only need to post the link in your browser in a different tab then go back to Integromat.
Create a step in the scenario to get the data. This will likely be a HTTP request module, this module can request data and parse the response.
Create a webhook response. This will return the information to the badge to tell it what to do, this will include your style information, badge contents etc.
Activate your scenario. You will have to do this so allow the webhook to run whenever it gets a request. Toggle the switch to run instantly.
Set up your badge! Go to shields.io json endpoint page and enter your webhook URL there, if you did everything right, you should see your badge pop up.
You don't need to know code to make yourself a dynamic shields.io badge Click To TweetSet up badges with code (Cloudflare)
This method requires you have at least one domain on Cloudflare, the free plan works for this.
Signup for an account and add a domain if you haven’t done already. You will need to proxy a domain for this.
Create a worker and add code to it. This will run your code and fetch your information for the badge. They have some documentation on this. This is the code I use for QuoteBot’s badge.
(Go easy on me. Discord doesn’t have a API where you can get server info and I don’t write in JavaScript except when I have to)
Deploy this worker on a route. Put it somewhere out of the way, I put mine at /api/badges/servers, you don’t need to hide it, it will be in the badge URL anyway.
Set up your badge! Go to the shields.io json endpoint page and enter your worker URL there, if you did everything right, you should see your badge pop up.
Make a cloudflare worker to create a dynamic shields.io badge for your site Click To TweetTroubleshooting
You might encounter some issues when doing this. If you receive Custom badge: unparseable response badge make sure to check :
- The API is returning a
stringfor the message field, not anything like anintor afloat. - You haven’t passed monthly quotas for your selected service, else it will not return the expected result. If this happens you’ll probably get an email alerting you.
- It isn’t the wrong URL, put the URL into your browser and see if it returns the JSON response you wanted. (If it returns something else than what you expected, check your configuration)
Conclusion
Shield badges are a very nice customizable way to display data, their caching system makes them ideal for integration services. And they’re not just limited to numbers, they’re usually used to display Twitter handles, and if a GitHub build has passed. What do you display in shield badges?
How to create a custom shields.io badge for your site Click To Tweet