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

Correction of format and typos #79

Merged
merged 4 commits into from
Oct 30, 2023
Merged

Correction of format and typos #79

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b9488e1
fix: format and typos
dfischer-tech Oct 22, 2023
b1f780a
fix: typos
dfischer-tech Oct 23, 2023
3bb1aa9
Update date-time format
rartych Oct 24, 2023
f323b32
Update date-time string format
rartych Oct 24, 2023
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
4 changes: 2 additions & 2 deletions documentation/API-DocumentationTemplate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@
|Documentation|Details|This is an optional section/placeholder. It could include some detailed descriptions or diagrams explaining things in further details and the subsection heading could be changed accordingly.| |
| |Endpoint definitions | What does each endpoint do is a critical part of the API documentation. It explains the consumer/developer your internal system. The documentation should explain what an endpoint is for and how it relates to other endpoints. It should also document:</br> - HTTP verb methods supported. </br> - Parameters along with description </br> - HTTP codes expected + HTTP response bodies </br> - HTTP Request and Response headers </br> - Pagination details if applicable </br>If there are any constraints for an endpoint, it should be documented in this section. </br> It should be made clear if certain endpoints are restricted to only certain roles/users. | Yes |
| |Errors|Error types along with error codes summary table can offer a good reference for the developers working with the API | Yes |
| |Policies|How the developer can discover the usage policy for each endpoint - e.g. limits on requests per second, any regional limitations on what can be returrned in the resource representation, etc. These policies will be operator-specific but the mechanism to discover them should be consistent | No |
| |Policies|How the developer can discover the usage policy for each endpoint - e.g. limits on requests per second, any regional limitations on what can be returned to the resource representation, etc. These policies will be operator-specific, but the mechanism to discover them should be consistent | No |
| |Code snippets| Copy-paste sample code snippets help developers to get started right away. It helps provide a rich developer experience. This can include sample request examples, and the ability to execute samples directly from the documentation Web page (as per Open API). | No |
| |FAQs| List of frequently asked questions by the early developers/users of the API |No |
| |Terms|Terms of Service |No (N/A for Camara|
| |Release Notes|Listof all changes included in the release |Yes|
| |Release Notes|List of all changes included in the release |Yes|
| |Pricing |Details about pricing |No (N/A for Camara)|
|API Spec || Complete API Spec in YAML format | Yes |
4 changes: 2 additions & 2 deletions documentation/API-Readiness-Checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
| 2 |API Implementation | N | |
| 3 |API Documentation | Y |The API specification should include all the needed documentation. |
|4 |User Stories | Y | https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md |
| 5 |API test cases and documentation | Y | A Gherkin feature file will be added to the main subproject repo and this will fulfill the minimum criteria of readiness w.r.t API test cases and documentation. If subprojects also intend to add test implementations, an aligned single implementation that is agreed amongst all provider implementors could be added to the main subproject repo. If no alignment is possible, each provider implementor will add the test implementation to their own repos |
| 6 |Tested by atleast 2 operators | Y | |
| 5 |API test cases and documentation | Y | A Gherkin feature file will be added to the main subproject repo and this will fulfil the minimum criteria of readiness w.r.t API test cases and documentation. If subprojects also intend to add test implementations, an aligned single implementation that is agreed amongst all provider implementors could be added to the main subproject repo. If no alignment is possible, each provider implementor will add the test implementation to their own repos |
| 6 |Tested by at least 2 operators | Y | |
| 7 |Security review | Y | Spec contributions should include a security scheme section that complies with the AuthN&AuthZ techniques agreed in Commonalities. |

Loading