Skip to content

Add sorting support to Container Registry Tags REST API endpoint

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 (merged) (keyset pagination support) and addresses the sorting limitation mentioned in #432470 (closed).

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:

# 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 (closed) (Container registry REST API: order by published_at)
  • Related MR: !143730 (merged) (Add keyset pagination to Container Registry Tags REST API) - provides the foundation for efficient sorting implementation

Related Resources

Edited by 🤖 GitLab Bot 🤖