Decide on some conventions for allowing the user to specify the URL we should call

[chris48s]

Over the last 10+ years we have accumulated a lot of code written by a lot of different people.
In general, I think we've done a reasonable job of enforcing relatively consistent code styles and naming conventions, via documentation and/or lint rules, but there are obviously some exceptions.

One significant "blind spot" where we have a lot of variance is params for allowing the user to specify (part of) the URL we should call to get data for the badge.

This comes out of a conversation in #10792 (comment)
Also related to #10806

Underneath this, there are a couple of cases.

1. The first is where the entire URL we're going to call is a param

So this is like the dynamic json/yaml/xml/toml badges or the endpoint badge
but there are also some others like
OSSLifeCycle or Python Version from pyproject.toml

2. The second case is where part of the URL we're going to call is hard-coded, but the user can specify the "base url". There may or may not be a default. This is important for services which are distributed or self-hosted.

Within this, there are 2 patterns. By far the most common of these is that the param is a URL (including the protocol:// )

Some examples:

shields/services/teamcity/teamcity-build.service.js

Lines 33 to 36 in 41d072e

	queryParam({
	name: 'server',
	example: 'https://teamcity.jetbrains.com',
	}),

shields/services/gitlab/gitlab-forks.service.js

Lines 35 to 38 in 41d072e

	queryParam({
	name: 'gitlab_url',
	example: 'https://gitlab.com',
	}),

shields/services/jira/jira-sprint.service.js

Lines 52 to 56 in 41d072e

	queryParam({
	name: 'baseUrl',
	example: 'https://issues.apache.org/jira',
	required: true,
	}),

Then there is a second less common pattern where the "base URL" is just a domain (excluding the protocol)

I think the only two examples we have of this pattern are Matrix and Mastodon:

shields/services/mastodon/mastodon-follow.service.js

Lines 38 to 41 in 41d072e

	queryParam({
	name: 'domain',
	example: 'mastodon.social',
	}),

shields/services/matrix/matrix.service.js

Lines 88 to 91 in 41d072e

	queryParam({
	name: 'server_fqdn',
	example: 'matrix.org',
	}),

If anyone knows of another example of this then let me know, but I think there are only 2 cases of this.

As alluded to in #10792 (comment) this only works for services where the thing lives on a domain or subdomain but can't live under a subdirectory. So what I mean by this is some services don't have to live at the root of a (sub-)domain. For example, a JIRA instance might live at a URL like https://jira.spring.io or a URL like https://issues.apache.org/jira . If you express this as "domain" or "fqdn", it doesn't account for the second of those cases.

In my view, we should:

1. Document that when we accept a "base url" type param, it a full URL (including protocol://)
2. Fix the two exceptions to this (matrix, mastodon)

Mainly because this is what the majority of cases do, and playing the hand we've got this is the easiest way to make this consistent.

There are a couple of ways we can change the documented query params but maintain compatibility with an older format. One way we can do it is with redirects. Another would be to write the queryParamSchemas to accept both formats but only document one. This shouldn't be a big deal to fix these two cases and maintain compatibility.

There is one argument put forward in https://github.com/badges/shields/pull/10792/files#r1904687991 about forcing HTTPS.

Personally, I'd say the way we do that is by making the validator we use on the query param

Joi.string().uri({ scheme: ['https'] })

rather than

Joi.string().uri({ scheme: ['http', 'https'] })

which is what we use at the moment

shields/services/validators.js

Lines 64 to 71 in 41d072e

	/**
	* Joi validator that checks if a value is a URL
	*
	* TODO: This accepts URLs with query strings and fragments, which for some purposes should be rejected.
	*
	* @type {Joi}
	*/
	export const optionalUrl = Joi.string().uri({ scheme: ['http', 'https'] })

I think if we want to force HTTPS, that's the way to do it. We can declare a shared validator for a URL (accepting HTTPS only) and use that for new services if we want. I'd rather see us do this than tell the user to split their URL into parts for us.