Define API URI naming conventions

WFM in general, with one exception:

/xb-api/v1/{resources} [ /{resourceId} [ /{subCollections} [ /{resourceId} ] ] ]

-1 to versioning the API at this time, because that implies it's a public API. It is not. Defining a public API for this that we provide BC for is definitely not in scope.

If you really want to have it, then let's use:

/xb-api/v0/{resources} [ /{resourceId} [ /{subCollections} [ /{resourceId} ] ] ]

(with v0 matching XB's major version: 0.x)

P.S.: I do not understand why

We should also avoid /xb/ if we're going to use that path for administrative UI routes.

matters? /xb-api/… vs /xb/api/… are essentially the same?

Instead of /v0/, perhaps we can make it even clearer that it's an internal API by naming it /internal/?

#5++

Re: versioning the API, I only proposed it to consider because it's a common industry pattern. If we're not making any stability promises for contrib modules to use it, for example, I see no reason for it. In that case, I don't think we need /internal/ either.

As to avoiding /xb/, I wanted to prevent "namespace" collisions, since we already have some routes at /xb/. But having considered it a little more, I don't think I'm actually worried about it as long as we don't anticipate wanting to use /xb/api/ for anything else. In fact, there would be a certain elegance in it if we can keep everything under /xb/. Perhaps we could do something like /xb/api/ and /xb/routes/ or similar.

I'm updating the issue description accordingly.

I agree with @traviscarden - versioning is a standard practice. It also means we can evolve over time. If we decide the API for an endpoint changes, we start a new version and emit deprecations from the old one.

Another alternative practise is to require consumers to set the version # via an accept header - e.g. github has Accept: application/vnd.github.v3+json

I think it's easier to just put it in the URL, so plus one for v0