Skip to content

Geo Primary Verification API: Add links field to GET api/v4/admin/data_management/:model

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Why are we doing this work

This work builds upon the foundation established in #537707 (closed) to enhance the Geo Primary Verification API with contextual navigation links. Taking inspiration from #521274, we need to add a links field to the :model API response that provides users with relevant actions and documentation for each model.

This enhancement will improve the user experience by providing direct access to:

  • View the actual model instance
  • Access relevant documentation
  • Navigate to troubleshooting resources

The links field will contain an array of link objects with type, text, and link properties, enabling the frontend to render contextual navigation options for each model.

Relevant links

  • More on the links discussion in: #521274

Implementation plan

  1. Extend the EE::API::Entities::Model entity to include the links field:

    expose :links do |model|
  generate_model_links(model)
end

  2. Create a link generation service that builds contextual links based on the model type:

    def generate_model_links(model)
  links = []
  
  # View model link
  if model.respond_to?(:web_url)
    links << {
      type: "view_model",
      text: "View #{model.class.name.downcase}",
      link: model.web_url
    }
  end
  
  # Model documentation link
  links << {
    type: "model_docs",
    text: "#{model.class.name} docs",
    link: documentation_url_for_model(model.class)
  }
  
  # Troubleshooting link (Geo-specific)
  if geo_enabled? && model.respond_to?(:replicator_class)
    links << {
      type: "troubleshooting",
      text: "Troubleshooting docs",
      link: geo_troubleshooting_url_for_model(model.class)
    }
  end
  
  links
end

  3. Create helper methods for generating documentation URLs:

    def documentation_url_for_model(model_class)
  # Map model classes to their documentation URLs
  case model_class.name
  when 'Project'
    'https://docs.gitlab.com/user/project/organize_work_with_projects'
  when 'Group'
    'https://docs.gitlab.com/user/group/'
  # Add more mappings as needed
  else
    'https://docs.gitlab.com'
  end
end

def geo_troubleshooting_url_for_model(model_class)
  # Map to Geo-specific troubleshooting documentation
  'https://docs.gitlab.com/administration/geo/replication/troubleshooting/common/'
end

  4. Update API documentation to reflect the new links field in the response schema

  5. Add comprehensive tests covering:

    • Link generation for different model types
    • Proper URL formatting
    • Conditional link inclusion based on model capabilities
    • Geo-enabled vs non-Geo environments

Issue generated with Duo Agentic Chat 🙌

Edited by 🤖 GitLab Bot 🤖