Use Grape's namespace DSL more heavily

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

• Close this issue

We currently don't use Grape's namespace DSL as much as we could. This would have a few advantages:

• Group endpoints that share a common root path
• Document once the params shared in these routes

Example:

resources :projects do
  params do
    requires :id, type: String, desc: 'The ID of a project'
  end
  route_param :id do
    resources :builds do
      params do
        requires :build_id, type: Integer, desc: 'The ID of a build'
      end
      route_param :build_id do
        desc 'Get a specific build of a project' do
          success Entities::Build
        end
        get do
          [...]
        end

        desc 'Download the artifacts file from build' do
          detail 'This feature was introduced in GitLab 8.5.'
        end
        get :artifacts do
          [...]
        end
      end
    end
  end
end

Or to reduce the deeply-nested blocks (which is better IMO) we could do the following:

params do
  requires :id, type: String, desc: 'The ID of a project'
end
namespace 'projects/:id' do
  params do
    requires :build_id, type: Integer, desc: 'The ID of a build'
  end
  namespace 'builds/:build_id' do
    desc 'Get a specific build of a project' do
      success Entities::Build
    end
    get do
      [...]
    end

    desc 'Download the artifacts file from build' do
      detail 'This feature was introduced in GitLab 8.5.'
    end
    get :artifacts do
      [...]
    end
  end
end

/cc @razer6 @smcgivern @DouweM @zj @rspeicher