API SHOULD follow best practices

[odungern]

e.g. Microsoft API Guidelines

[oalt]

Some links to best practices: http://apistylebook.com/design/guidelines/ https://restfulapi.net/resource-naming/ https://www.merixstudio.com/blog/best-practices-rest-api-development/

[odungern]

Also: http://apistylebook.com/design/guidelines/google-api-design-guide

[odungern]

With respect to our discussion REST URL-elements (tags): camelCase or hyphenated ( ../dataTypes/,, vs. ../data-types/..):

• Both are basically possible.
• hyphenated is more widely used than camelCase.
• JS does not support hyphens in an id
• Roy Fieldings arguments on the matter are most convincing to me.

BUT: I think it is important to have the same tags/tokens in the schema and the API (see #5).

My proposal:

• use all lowercase tags starting SpecIF v1.0, both in the schema and the API.
• means we will say datatypes, propertyclasses, resourceclasses and statementclasses - in the schema there are no other in camelCase, so far.
• I think those are not too difficult to read, so that using a dash is not really a 'must'.

What do you think: @oalt @oeichmann @S-Ruesch ?

[S-Ruesch]

My proposal:

• use all lowercase tags starting SpecIF v1.0, both in the schema and the API.
• means we will say datatypes, propertyclasses, resourceclasses and statementclasses - in the schema there are no other in camelCase, so far.
• I think those are not too difficult to read, so that using a dash is not really a 'must'.

In the schema there are more camelCase tags, for example changedAt, changedBy or specifVersion. Or am i wrong? I think i would prefer camelCase or hyphenated for better readability. But i don't have a favorite naming convention.

[odungern]

• You are right indeed, there are several properties with camelCase, as well.
• To be consistent, those would be all lowercase, too, according to my proposal. I.e. changedat, etc.
• Readability is an often cited and valid argument for camelCase or hyphenated.
• The schema isn't seen at all (just prepared once and then pulled by schema checkers).
• The API is seen by the programmers ... and also soon covered by some libraries.
• And there are programmers that don't like using the shift key ...
• Summarizing I think readability is less of a concern.

More important is in my opinion the consistency between schema and API as well as the consistency with standards in various technologies, from JS, JSON, XML and all of the W3C web standards. Then, we arrive at the least common denominator, the lowercase version.

[oalt]

I do not like the idea to give up camel case in the SpecIF schema. I think this is not good for the readability of the JSON data. And I repeat my argumentation I said in the Telco: Different languages resp. technologies have different coding standards. JSON uses camel case in the most cases and Web APIs use the notation with lower case and '-' symbol separation very often. At the end all the names mean the same thing! So for me it would be not the most important thing to have equal formatting for the JSON and the WebAPI. One example for the "diversity approach" is the OpenAPI code generator: From the same OpenAPI spec file it generates code for different languages in different formatting. Example: GET /data-types will result in

• getDataTypes() for Java or JavaScript/TypeScript
• GetDataTypes() for C# and so on...