new rule for using content negotiation #686
Conversation
|
👍 in principle. |
|
👍 |
| requested URI can be used to indicate that the returned resource is subject | ||
| to content negotiations, and that the value provides a more specific | ||
| requested URL can be used to indicate that the returned resource is subject | ||
| to <<244, content negotiations>>, and that the value provides a more specific |
There was a problem hiding this comment.
Why change URI to URL? (I guess in this case it's both, but I think URI is more commonly used nowadays (and also in the next bullet point.)
There was a problem hiding this comment.
I'm not sure that URI is more used than URL. In our Guidelines I see 20 URI and 22 URL occurrences.
I try to consistently prefer the more specific URL term, if appropriate.
Therefore changed here.
There was a problem hiding this comment.
I would use URI and URL in there different meanings as appropriate. The point here is, that we talk about URL in case of endpoints since they are meant to be resolved via the HTTP protocol. In cases where we just identify the resource without telling whether we plan to make it accessible via HTTP, I would use URI.
| == {MUST} property names must be ASCII snake_case (and never camelCase): `^[a-z_][a-z_0-9]*$` | ||
| == {MUST} property names must be snake_case (and never camelCase) | ||
|
|
||
| Property names are restricted to ASCII strings. The first | ||
| character must be a letter, or an underscore, and subsequent | ||
| Property names are restricted to ASCII snake_case strings matching regex `^[a-z_][a-z_0-9]*$`. | ||
| The first character must be a lower case letter, or an underscore, and subsequent | ||
| characters can be a letter, an underscore, or a number. | ||
|
|
||
| (It is recommended to use `_` at the start of property names only for keywords like `_links`.) | ||
| Examples: | ||
|
|
||
| [source] | ||
| ---- | ||
| customer_number, sales_order_number, billing_address | ||
| ---- |
There was a problem hiding this comment.
the change in this file seems unrelated to the rest of the changes, and I'm also not sure it's an improvement.
We had this regexp intentionally as part of the header, so it's visible already in the table of contents, and now you've moved it into the text?
There was a problem hiding this comment.
a) Yes, this change is not related to rest of the changes -- my fault, I originally intended to do the commit on the branch of parallel #690
b) I moved the regex from the header into the text because (i) it IMO improves readability -- being a regex expert is not required to apply the guidelines, and (ii) to be consistent with other rules like
https://opensource.zalando.com/restful-api-guidelines/#240
https://opensource.zalando.com/restful-api-guidelines/#130
https://opensource.zalando.com/restful-api-guidelines/#215
https://opensource.zalando.com/restful-api-guidelines/#129
|
👍 |
|
|
||
| Property names are restricted to ASCII strings. The first | ||
| character must be a letter, or an underscore, and subsequent | ||
| Property names are restricted to ASCII snake_case strings matching regex `^[a-z_][a-z_0-9]*$`. |
|
👍 |
No description provided.