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

The URI naming was made consistent in 📌 Make all XB HTTP API routes consistently prefixed Active 😄

That also means that versioning it today would be trivial.

@traviscarden, would you like to take that on? :D

On it, @wim leers!

I started to create a static helper to centralize the path generation logic (because it is a little inconsistent), but most of the API path strings were in YAML and JavaScript files, so once I decided not to use it in test classes (because it would make them less expressive), there weren't enough uses left to justify its existence. I'm basically explaining why I didn't have an MR in the 5 minutes it took to do a search-and-replace. 😛 Anyway, here it is. ^

Thanks!

There's another merge conflict, working on resolving it.

DxRouteConsistencyTest is not currently passing — once it is, I'm looking forward to merging this, and I'm sure @larowlan does too 😄

Thanks so much! Let’s land this today so y’all can stop chasing HEAD! 🙈

Automatically closed - issue fixed for 2 weeks with no activity.