Property Naming

[nateklaiber]

According to Property Names

camelCase MUST be used for all property names in both request and response payloads

According to the ECMA definition for the JSON data interchange syntax:

The JSON syntax does not impose any restrictions on the strings used as names. [...] These are all semantic considerations that may be defined by JSON processors or in specifications defining specific uses of JSON for data interchange.

As I believe most API developers can attest, there are many platforms in production today that have committed to a variance here and are unable to change it as it would be a breaking change. If they've committed to camelCase, then a change to snake_case would be difficult.

I would push back against the MUST part here for a simple reason. camelCase or PascalCase both leave room for issues, ambiguity, or breaking the principle of least surprise. If I use snake_case, then it's much more clear. I don't have to think between entityUrlId, entityURLID, entityUrlID, or entityURLId (all depend on what the platform application designates as their own inflections). If I use snake_case, then it's entity_url_id without the ambiguity.

I use snake_case as a convention to eliminate any confusion at that level.

I know there could still be ambiguity on where separators are placed, but that would also apply to all of the possible casings.

[travisgosselin]

I completely agree with you @nateklaiber . I am also a snake case fan given its clarity, its native usage in javascript/typescript deserialization, etc. However, more important than the chosen serialization casing is its consistency. If we were starting an ecosystem from scratch, I would probably go with snake_case as a personal preference. But interestingly enough, camelCase is an incredibly popular default method of property serialization in different frameworks.

Like many organizations, SPS has an interesting bifurcation in casing today in its APIs internally. Based on some internal technical reasons, existing usage, and pre-existing standards we were starting from, the SPS API Standards have landed on camelCase. It is essential for us to drive consistency in our APIs and so this is not an area we can flex at all with teams building on our standards, it is a definite MUST.

We did, however, recognize the inconsistency you mention when used with acronyms and abbreviations in resourceID vs resourceId for example. We have a follow-up line indicating such usage is wrong. The purity of the camelCase should always be maintained: resourceId

All acronyms MUST follow camelCase standards if they are part of the property name.

// INCORRECT
ID
documentID
imageURL
 
 
// CORRECT
id
documentId
imageUrl