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

Jump to bottom

reformat tables, grammar and style issues in documentation-files #234

Merged
merged 7 commits into from
Jul 2, 2024
Merged

reformat tables, grammar and style issues in documentation-files #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5e6343a
fix: reformat tables, grammar and style
maxl2287 Jun 11, 2024
169ebe2
Update documentation/Linting-rules.md
maxl2287 Jun 18, 2024
c830bf3
Merge remote-tracking branch 'refs/remotes/origin/main' into fix/refo…
maxl2287 Jun 18, 2024
2018a05
fix: update API-Testing-Guidelines.md after merge conflict resolvent
maxl2287 Jun 18, 2024
615c0a9
Update documentation/API-Testing-Guidelines.md
maxl2287 Jun 19, 2024
959c064
Update documentation/API-Testing-Guidelines.md
maxl2287 Jun 19, 2024
40c8899
Merge remote-tracking branch 'refs/remotes/origin/main' into fix/refo…
maxl2287 Jul 1, 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
30 changes: 15 additions & 15 deletions documentation/API-DocumentationTemplate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# API documentation template

| Section | Sub-section | Description | Mandatory |
|----|---|---|-|
| Overview | Introduction | This section gives an overview of the API. It explains the use of the API and gives an insight on its benefits. A few lines on some standard use cases can help better explain the API | Yes |
|| Quick Start|It explains how developers can get started with this API. A good example is the Stripe-API documentation: https://stripe.com/docs/api ||
|Authentication and/or Authorization | |It explains how developers/consumers can access the API. Failure to document the authN-authZ schema in a simple and precise way can deter first time API users . |Yes|
|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 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|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 |
| Section | Sub-section | Description | Mandatory |
|-------------------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
| Overview | Introduction | This section gives an overview of the API. It explains the use of the API and gives an insight on its benefits. A few lines on some standard use cases can help better explain the API | Yes |
| | Quick Start | It explains how developers can get started with this API. A good example is the Stripe-API documentation: https://stripe.com/docs/api | |
| Authentication and/or Authorization | | It explains how developers/consumers can access the API. Failure to document the authN-authZ schema in a simple and precise way can deter first time API users . | Yes |
| 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 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 | 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 |
Loading