search

camaraproject / Commonalities

Repository to describe, develop, document and test the common guidelines and assets for CAMARA APIs
Apache License 2.0
14 stars 28 forks source link

Create a CAMARA cheatsheet.md #319

Open Kevsy opened 1 month ago

Kevsy commented 1 month ago

Problem description

'Cheatsheets' are a convenient way to summarise editing rules and examples, e.g. GitHub Markdown Cheatsheet.

A CAMARA Cheatsheet would help API editors quickly check rules and conventions. I suggest this cheatsheet.md to be a separate document to the new slimline design guidelines (#64), and would need to be synchronised with any new or change design rules.

Example content:

CAMARA syntax cheatsheet

Case conventions

Information item Convention Example
API name kebab-case simple-edge-discovery
Path kebab-case /customer-segments
OperationId camelCase getData

Scopes

Structure: api-name:[resource:]action Format: kebab-case, colon separated Example: qod:qos-profiles:read

etc.

Possible evolution

Alternative solution

The cheatsheet could be incorporated into the new slimline design guidelines (#306) as an appendix.

Additional context

patrice-conil commented 1 month ago

Hi @Kevsy, Great idea!

PedroDiez commented 1 month ago

Yes, think it is very useful.

Maybe could be also a good idea to reference this document in "Create Camara-OAS-Sections-Guidelines.md" PR#317 within section ## Introduction, so as the information is linked and a reader can easily find it. cc @shilpa-padgaonkar