<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=573326) </details> <!--IssueSummary end--> <!-- Proposed Issue Title: Add sorting support to Container Registry Tags REST API endpoint --> <!-- This template is a great use for issues that are feature::additions or technical tasks for larger issues.--> ### Proposal Add comprehensive sorting support to the Container Registry Tags REST API endpoint (`/api/v4/projects/:id/registry/repositories/:repository_id/tags`) to enable developers to sort tags by multiple fields, matching the functionality already available in the GraphQL API. This issue builds upon the work done in !143730 (keyset pagination support) and addresses the sorting limitation mentioned in #432470. 🛠️ with ❤️ at Siemens #### Problem Statement The REST API currently only supports basic name-based sorting, forcing API consumers to: - Fetch all tags and sort client-side, which is inefficient for large tag lists and increases bandwidth usage - Use GraphQL as a workaround, which has pagination issues and adds unnecessary complexity for simple sorting needs - Deal with inconsistency between GraphQL and REST API capabilities This limitation impacts developers using `python-gitlab` or direct REST API calls who need to implement container registry optimization strategies, find latest tags efficiently, or implement cleanup workflows based on tag age. #### Proposed Solution Enhance the Container Registry Tags REST API endpoint with standard GitLab sorting parameters following established REST API conventions: **New API Parameters:** - **`order_by`**: Field to sort by - Supported values: `name`, `published_at`, `created_at`, `updated_at` - Default: `name` (maintains backward compatibility) - **`sort`**: Sort direction - Supported values: `asc`, `desc` - Default: `asc` **Example API Calls:** ```bash # Get tags sorted by publish date (newest first) GET /api/v4/projects/:id/registry/repositories/:repository_id/tags?order_by=published_at&sort=desc # Get tags sorted by creation date (oldest first) GET /api/v4/projects/:id/registry/repositories/:repository_id/tags?order_by=created_at&sort=asc # Get tags sorted by name (default behavior - backward compatible) GET /api/v4/projects/:id/registry/repositories/:repository_id/tags ``` #### Technical Implementation Details - Follows existing GitLab REST API sorting conventions (same `order_by`/`sort` pattern used in Issues, Merge Requests, etc.) - `published_at` sorting only available when GitLab API client is supported (`GitlabApiClient.supports_gitlab_api?`) - Graceful fallback to `name` sorting when `published_at` is not available - Backend infrastructure already supports this via `ContainerRepository#tags_page` method - Maintains full backward compatibility - existing API calls work unchanged - Reuses existing validation and error handling patterns from other GitLab APIs **Key Files to Modify:** - `lib/api/project_container_repositories.rb` - Add sorting parameters to tags endpoint - `lib/api/helpers/container_registry_helpers.rb` - Add sort validation helpers - `lib/api/entities/container_registry.rb` - Enhance TagDetails entity with timestamp fields - `spec/requests/api/project_container_repositories_spec.rb` - Add comprehensive sorting tests #### Success Criteria - [ ] REST API endpoint accepts `order_by` and `sort` parameters following GitLab conventions - [ ] Supports sorting by: `name`, `published_at`, `created_at`, `updated_at` - [ ] Maintains backward compatibility - existing API calls work unchanged - [ ] `published_at` sorting works when GitLab API client is available - [ ] Appropriate error messages for invalid parameters - [ ] Comprehensive test coverage including authorization, parameter validation, and edge cases - [ ] Updated API documentation with examples - [ ] Performance maintained - no degradation in API response times #### What does success look like, and how can we measure that? **User Impact Metrics:** - Developers can implement container registry cleanup workflows without client-side sorting - Reduced API response payload processing on client side for large tag lists - Consistent API experience between REST and GraphQL interfaces **Technical Metrics:** - API endpoint response times remain within acceptable limits (no regression) - Test coverage includes all sorting combinations and error scenarios - Zero breaking changes for existing API consumers #### Related Issues and Merge Requests - Related issue: #432470 (Container registry REST API: order by `published_at`) - Related MR: !143730 (Add keyset pagination to Container Registry Tags REST API) - provides the foundation for efficient sorting implementation #### Related Resources - [GitLab REST API Sorting Documentation](https://docs.gitlab.com/ee/development/api_styleguide.html#sorting) - [Container Registry API Documentation](https://docs.gitlab.com/api/container_registry.html#list-registry-repository-tags) - GraphQL implementation reference: `app/graphql/resolvers/container_repository_tags_resolver.rb` - Backend model: `app/models/container_repository.rb` (already supports sorting via `tags_page` method)