Tutorial: badge-urls


Badge URL Conventions

  • The format of new badges should be of the form /SERVICE/NOUN/PARAMETERS?QUERYSTRING e.g: /github/issues/:user/:repo. The service is github, the badge is for issues, and the parameters are :user/:repo.
  • The NOUN part of the route is:
    • singular if the badge message represents a single entity, such as the current status of a build (e.g: /build), or a more abstract or aggregate representation of the thing (e.g.: /coverage, /quality)
    • plural if there are (or may) be many of the thing (e.g: /dependencies, /stars)
  • Parameters should always be part of the route if they are required to display a badge e.g: :packageName.
  • Common optional params like, :branch or :tag should also be passed as part of the route.
  • Query string parameters should be used when:
    • The parameter is related to formatting. e.g: /appveyor/tests/:user/:repo?compact_message.
    • The parameter is for an uncommon optional attribute, like an alternate registry URL.
    • The parameter triggers application of alternative logic, like version semantics. e.g: /github/v/tag/:user/:repo?sort=semver.
    • Services which require a url/hostname parameter always should use a query string parameter to accept that value. e.g: /discourse/topics?server=https://meta.discourse.org.

It is convention to use the following standard routes and abbreviations across services:

  • Coverage: /coverage
  • Downloads or Installs:
    • Total: /dt - Use this even for services that only provide the total download/install data
    • Per month: /dm
    • Per week: /dw
    • Per day: /dd
  • Rating:
    • Numeric: /rating
    • Stars: /stars
  • License: /l
  • Version or Release: /v