Documentation: API routes and file structure

pbastia commented 1 month ago

Description:

After what was discussed during the API meeting and dev team agreements, we need to document in the API docs (docs/backend/api-design.md):

1) API routes don't need to mirror frontend routes. They should match the object they're fetching

GET "object-to-be-fetched/{id}"
GET "object-to-be-fetched?some_param=123&other_param=..."

example:
GET "report-version/{version_id}"
GET "facility-report/{facility_report_id}" OR "facility-report?...params..."

URI stands for "Uniform Resource Identifier" : the path should point at the resource we're dealing with
The payload/query params then can be used to filter, generate or modify the resource

2) API files should minimize the amount of routes they declare for readability & testability. Rule of thumb is one file per resource with GET PUT POST ...

example: report-version.py

File path can include subdirectories following the API endpoint's URL.

Acceptance Criteria:

Given I am a developer When I make a new API endpoint Then I know which route to assign to it, how parameters will be queried, and in which file to write it

Development Checklist:

[ ] api-design.md file updated
[ ] Meets the DOD

Definition of Ready (Note: If any of these points are not applicable, mark N/A)

[ ] User story is included
[ ] User role and type are identified
[ ] Acceptance criteria are included
[ ] Wireframes are included (if required)
[ ] Design / Solution is accepted by Product Owner
[ ] Dependencies are identified (technical, business, regulatory/policy)
[ ] Story has been estimated (under 13 pts)

Definition of Done (Note: If any of these points are not applicable, mark N/A)

[ ] Acceptance criteria are tested by the CI pipeline
[ ] UI meets accessibility requirements
[ ] Configuration changes are documented, documentation and designs are updated
[ ] Passes code peer-review
[ ] Passes QA of Acceptance Criteria with verification in Dev and Test
[ ] Ticket is ready to be merged to main branch
[ ] Can be demoed in Sprint Review
[ ] Bugs or future work cards are identified and created
[ ] Reviewed and approved by Product Owner

Notes:

-

pbastia commented 1 month ago

@Sepehr-Sobhani for API team visibility

Sepehr-Sobhani commented 1 month ago

In case we want to include it in docs: Path Parameters vs. Query Parameters We have used query params for paginating and sorting a list of items for a specific data grid.

bcgov / cas-reporting