Add pagination, search and a role filter to the organizations list endpoint
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 188
- Forks
- 142
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 21
Description
Suggested Feature / Enhancement
GET /api/v1/orgs returns every organization the requesting user can access in a single response. There is no pagination, no way to search and no way to filter by the user's role; the only filter available today is shared_with.
Add three things to the endpoint:
- Pagination — support the
pageandpage_sizequery params, the same way the projects and forms list endpoints already do. - Search — support a
searchquery param that matches against the organization's name and its username (theorgfield in the response). - Role filter — support a
rolequery param that returns only the organizations where the requesting user holds that role or a higher one. For example,?role=managerreturns the organizations the user manages or owns. This mirrors therolefilter on the v2 projects endpoint.
All three should be combinable with each other and with the existing shared_with filter, e.g. GET /api/v1/orgs?role=manager&search=health&page=1&page_size=20.
Benefits of implementing the feature/enhancement
- Users who belong to many organizations get a large response and a heavy query every time a client lists their organizations. Each item is also costly to build, since it includes the organization's users and their roles.
- Clients that show an organization picker or typeahead currently have to download the full list and filter it themselves. Server-side search lets them request only what matches.
- Clients that need "the organizations I can create a project in" or "the organizations I can transfer a project to" currently fetch every organization and look for their own entry in each
userslist. That only works while the client holds the full list. Once the list is paginated, a page may contain few or none of the matching organizations, so the role filter has to happen on the server. - It brings the endpoint in line with the projects, forms and data endpoints, which already paginate, and with the v2 projects endpoint, which already filters by role.
Suggested implementation plan(Steps to be taken to implement feature)
- Set
pagination_class = StandardPageNumberPaginationonOrganizationProfileViewSet. That class keeps the response body as a plain array and puts the page links in theLinkheader, so the response shape does not change for existing clients. - Give the list queryset an explicit, stable ordering (the model defines none), so pages do not overlap or skip records.
- Add DRF's
SearchFilterto the viewset'sfilter_backendswithsearch_fieldscoveringnameanduser__username, keeping the existing permission andshared_withfilters in place.UserViewSetalready uses the same approach. - Add an organization role filter backend modelled on
ProjectRoleFilter: read therolequery param, return a 400 for an unknown role name, take that role'sOrganizationProfilepermission set and filter withget_objects_for_user(..., any_perm=False)so the result is "that role and above". Group permissions should count, since organization roles can be granted through teams, and the result should agree with whatget_role_in_orgreports in each item'susers[].role. - Decide how to treat roles below
manager. OnOrganizationProfile, onlymanagerandownerhold permissions beyondview_organizationprofile, so a permission-based filter can tell apartowner,managerand above, and everyone else, but noteditorfromreadonlyormember. Supportingownerandmanagercovers the use cases above; lower role names could either be accepted (returning everything the user can view) or rejected. - Decide on backwards compatibility for callers that send no
pageparam: either always paginate with the default page size of 1000, as the projects endpoint does, or only paginate whenpage/page_sizeis supplied. - Add tests for paging,
page_sizelimits, theLinkheader, search by name and by username,role=managerreturning managed and owned organizations,role=ownerreturning only owned ones, an unknown role returning a 400, the filters combined with each other and withshared_with, and that a user never sees organizations outside their permissions through search or the role filter. - Document the new query params in
docs/orgs.rst.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with OrganizationProfileViewSet, then compare the pagination and role-filter implementations used by the projects and forms list endpoints, ProjectRoleFilter, and UserViewSet. Check the existing organization endpoint tests before adding coverage for pagination, search, roles, combined filters, permissions, and the Link header; update docs/orgs.rst when the behavior and backwards-compatibility choice are settled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend, documentation, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100