I know microsoft lika camelCase but all other seems to use hyphens
.
For example Zalando
Example paths:
/shopping-carts/{country}/{session-id}
/shopping-carts/{country}/{session-id}/items/{item-id}
/api-specifications/{docker-image-id}/apis/{path}/{file-name}
/api-specifications/{repository-name}/{artifact-name}:{tag}
/article-size-advices/{sku}/{sales-channel}
https://opensource.zalando.com/restful-api-guidelines/
The standard best practice for REST APIs is to have a hyphen, not camelcase or underscores. This comes from Mark Masse’s “REST API Design Rulebook” from Oreilly.
It is recommended to use the spinal-case (which is highlighted by RFC3986), this case is used by Google, PayPal, and other big companies.
Microsoft says: DO use kebab-casing (preferred) or camel-casing for URL path segments. If the segment refers to a JSON field, use camel casing.
api-guidelines/azure/Guidelines.md at vNext · microsoft/api-guidelines · GitHub
Seems to me that Microsoft recommends kebab-casing in this case (my case) since Im referring to a value in a field/attribute (type) and not to a JSON field??
Hyphens and camelcase as value in the type field (attribute) feels weird but I guess it has to be same as the URI to be consistent
Or use best of both worlds (combination).
If I understand it correct most (almost all) would recommend this solution:
endpoint name: /v2/school-units/{school-unit-code}
response:
{
“data”: {
“type”: “school-units”,
“id”: “1”,
“attributes”: {
// … this schoolunit’s attributes
},
“relationships”: {
// … this schoolunit’s relationships
}
}
}
json:api recommends:
endpoint name: /v2/schoolUnit/{school-unit-code}
response:
{
“data”: {
“type”: “schoolUnit”,
“id”: “1”,
“attributes”: {
// … this schoolunit’s attributes
},
“relationships”: {
// … this schoolunit’s relationships
}
}
}
best of both worlds:
endpoint name: /articles/1 HTTP/1.1
{
“data”: {
“type”: “article”,
“id”: “1”,
“attributes”: {
// … this article’s attributes
},
“relationships”: {
// … this article’s relationships
}
}
}
endpoint name: /v2/school-units/{school-unit-code}
response:
{
“data”: {
“type”: “schoolUnit”,
“id”: “1”,
“attributes”: {
// … this schoolunit’s attributes
},
“relationships”: {
// … this schoolunit’s relationships
}
}
}
I will have to think about whether we should follow json:api and use camelCase in the uri and value in attribute type or make an exception in this case since most standards recommends hyphens (URL is case sensitive, its good for SEO to use hyphens and so on).