# 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`