Documentation: API routes and file structure
- Dominant language
- No language data
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
#### 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
- [ ] Ticket created to update existing code
- [ ] 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:
-
Contributor guide
No contributing guide indexed for this repository
Research direction
Update docs/backend/api-design.md using the route, parameter, and file-organization guidance in the issue. Check that the acceptance criteria are addressed: a developer should be able to choose an endpoint route, determine how parameters are queried, and identify the file for a new API endpoint.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend, documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100