It should be forbidden to invent own path variable names

[christophfriedrich]

I'm currently building a "method name -> endpoint" map for the JS client's implementation of hasFeature (background: #125) and realised that it'll be very important that all back-ends adhere to the same syntax and names when paths incorporate variables. E.g. I hard-coded describeJob to belong to GET /jobs/{job_id} - but if some back-end outputs /jobs/{$jobId} as the path in its Capabilities, the check would result in a false-negative.

The API does already say:

Variables in the paths must be placed in curly braces, e.g. {process_id}, and have a self-speaking name. It is RECOMMENDED that the path variable names fully follow the API specification.

Measured by these rules, my "false-negative" example above would be completely valid. But it can make a lot of problems.

I don't see any reason why we should leave the possibility of inventing own names by only "recommending" that all names follow the spec. Demanding "self-speaking names" kind of cries "it's okay if you make up your own, just make sure that they're understandable". I don't see any use case for this. Only problems.

Therefore I would like to make that spec paragraph stricter by changing it to:

Variables in the paths MUST be placed in curly braces, e.g. {process_id}, and MUST NOT be pre- or postfixed (e.g. NO {$process_id}). Path variable names MUST fully follow the API specification, i.e. they MUST be part of a path given in the spec*. The spec shall only introduce self-speaking names, and these shall consist of lower-case alphanumeric characters + underscores only (i.e. "snake case").

*) I didn't know how to word this part, basically I want to achieve:

They MUST be part of this enum: "user_id" "job_id" .... If it's not in there, it's not allowed.

[m-mohr]

Have you checked the old implementation? This was already fail-safe in the old JS client.

[christophfriedrich]

I'm talking about what the API spec permits, not about the implementation of the JS client, so I'm a bit confused what you mean 🤔 I linked to the doc I read (the blue "say" above).

[m-mohr]

I'm neutral on this issue. We can require it, but the current state can also easily be implemented with regular expression. So maybe let's put this on hold and wait how strict the back-ends follow this standard and reconsider changing it just before a 0.4 release.

[christophfriedrich]

I'd prefer to force the back-ends to follow the spec, because that's what a spec is for, but I can deal with your suggestion.

[m-mohr]

Fixed for API v0.4.