Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create Camara-OAS-Sections-Guidelines.md #317

Draft
wants to merge 10 commits into
base: main
Choose a base branch
from
+108 −0
Draft

Create Camara-OAS-Sections-Guidelines.md #317

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
a1af8e8
Create Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
5b341b4
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
f2bb086
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
707dcdc
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
ae1cec9
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
cfa4ba9
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
ca98362
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
7975033
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
0d16b91
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
191dfe1
Update Camara-OAS-Sections-Guidelines.md
shilpa-padgaonkar Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Loading
Loading status checks…
Update Camara-OAS-Sections-Guidelines.md
@shilpa-padgaonkar
shilpa-padgaonkar authored Oct 15, 2024
commit 0d16b91710ce433c014ccaea5e65f3639c35a94d
4 changes: 3 additions & 1 deletion documentation/Camara-OAS-Sections-Guidelines.md
View file
Original file line number Diff line number Diff line change
@@ -57,7 +57,7 @@ info:
Title describes the API shortly. The title shall not include the term "API" in it.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "Title" should be the "formal" (or "friendly") name of the API, rather than a free text description. Ideally, this name would also documented by API Backlog, though this table would need to be updated as it is currently sub-project rather than API centric.

"Formal" names will be important for marketing purposes. Whilst we can be sure all implementations will use, for example, the name /number-verification within the path, we cannot be sure that the associated implementation documentation will use the name "Number Verification".


#### Description
Description should provide a slightly longer description of the API as compared to the title.
No special restrictions specified in Camara.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the description shall include the user documentation for the API.
as well as a copy from the section from the ICM guidelines on the auth flows applicable to the API.


#### Version
APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group.
@@ -104,3 +104,5 @@ For the below example, the API-name would be location-verification.
API-Version shall be same as the [Version](#version) in the info object.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shall be a "v" concatenated with the MAJOR version number of the version field in the info object.
A CAMARA specific exception is that for APIs with version 0.y.z, the both the MAJOR and the MINOR version number are included in the , e.g. simple-edge-discovery/v0.3

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this should probably reference the section on API versioning in the API design guidelines


### Paths
No special restrictions or changes specified in Camara.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this be added to the end of the API Guidelines where there is a section on the OAS specification ? else this risks to create duplication / divergence