Alignment with API design guidelines

[jlurien]

Some weeks ago, a set of API design guidelines have been approved in commonalities.

Regarding terminolgy and style:

• Reduce telco-specific terminology in API definitions.
  • This is treated in issue #90.
• URI paths in lowercase and separated-by-hyphens.
  • Our paths are single word and already in lowercase
• OperationIds are defined in lowerCamelCase.
  • We are already compliant
• Objects are defined in CamelCase inside properties field. This affects declarations within definitions that are $ref in other parts.
  • We are already compliant
• API input and output business data will follow the snake_case notation.
  • We are NOT compliant. This affects property names.

Errors must include:

• A field status, which can be identified in the response as a standard code from list of Hypertext Transfer Protocol (HTTP) response status codes.
  • We have to add it to our model.
• A unique error code, which can be identified and traced for more details. It must be human readable; therefore, it must not be a numeric code. In turn, to achieve a better location of the error, you can reference the value or field that is causing it, and include it in the message.
  • We should review our current codes and probably define new codes for expected logical errors.
• A detailed description of message.
  • We are already compliant.

Proposed actions

• Most of changes apply to current property names, as they must be formattted in snake_case. This can be addressed together with issue #90 in a new PR, when new terms are agreed.

• We have to adapt errors, adding status, and at a same time we could enhance current documentation and examples. This can be done in separate PR.

[hdamker]

Suppose this issue is done:

• Most of changes apply to current property names, as they must be formattted in snake_case. This can be addressed together with issue #90 in a new PR, when new terms are agreed.

The final decision in Commonalities was camelCase for property names, which we will continue to use. Also the new terms are applied (with #129)

• We have to adapt errors, adding status, and at a same time we could enhance current documentation and examples. This can be done in separate PR.

Done with #104

[hdamker]

All done.