bcgov / bcgov/cas-reporting

Documentation: API routes and file structure

Open
#347 2 comments 0 reactions 0 assignees View on GitHub
API attn: Devs BACKLOG Backlog Refinement Good First Issue KEEP User Story
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.