Support template_project_id parameter in project creation API

This is a follow-up to
https://gitlab.com/gitlab-org/gitlab/merge_requests/18178, which
introduced this parameter in lieu of `template_name` to avoid ambiguity
in which project should serve as the template.

changelogs/unreleased/sh-support-project-template-id-in-api.yml

+---
+title: Support template_project_id parameter in project creation API
+merge_request: 20258
+author:
+type: added

doc/api/projects.md

@@ -948,6 +948,7 @@ POST /projects
 | `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
 | `initialize_with_readme` | boolean | no | `false` by default |
 | `template_name` | string | no | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template |
+| `template_project_id` | integer | no | **(PREMIUM)** When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. |
 | `use_custom_template` | boolean | no | **(PREMIUM)** Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template |
 | `group_with_project_templates_id` | integer | no | **(PREMIUM)** For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true |
 

ee/spec/requests/api/projects_spec.rb

@@ -205,6 +205,7 @@ describe API::Projects do
       end
 
       it 'returns a 400 error for an invalid template name' do
+        project_params.delete(:template_project_id)
         project_params[:template_name] = 'bogus-template'
 
         expect { post api('/projects', user), params: project_params }
@@ -213,23 +214,52 @@ describe API::Projects do
         expect(response).to have_gitlab_http_status(400)
         expect(json_response['message']['template_name']).to eq(["'bogus-template' is unknown or invalid"])
       end
+
+      it 'returns a 400 error for an invalid template ID' do
+        project_params.delete(:template_name)
+        new_project = create(:project)
+        project_params[:template_project_id] = new_project.id
+
+        expect { post api('/projects', user), params: project_params }
+          .not_to change { Project.count }
+
+        expect(response).to have_gitlab_http_status(400)
+        expect(json_response['message']['template_project_id']).to eq(["#{new_project.id} is unknown or invalid"])
+      end
     end
 
     context 'with instance-level templates' do
       let(:group) { create(:group) }
       let!(:project) { create(:project, :public, namespace: group) }
       let(:new_project_name) { "project-#{SecureRandom.hex}" }
-      let(:project_params) do
-        {
-          template_name: project.name,
-          name: new_project_name,
-          path: new_project_name,
-          use_custom_template: true,
-          namespace_id: group.id
-        }
+
+      context 'using template name' do
+        let(:project_params) do
+          {
+            template_name: project.name,
+            name: new_project_name,
+            path: new_project_name,
+            use_custom_template: true,
+            namespace_id: group.id
+          }
+        end
+
+        it_behaves_like 'creates projects with templates'
       end
 
-      it_behaves_like 'creates projects with templates'
+      context 'using template project ID' do
+        let(:project_params) do
+          {
+            template_project_id: project.id,
+            name: new_project_name,
+            path: new_project_name,
+            use_custom_template: true,
+            namespace_id: group.id
+          }
+        end
+
+        it_behaves_like 'creates projects with templates'
+      end
     end
 
     context 'with group templates' do
@@ -238,18 +268,36 @@ describe API::Projects do
       let(:group) { subgroup }
       let!(:project) { create(:project, :public, namespace: subgroup) }
       let(:new_project_name) { "project-#{SecureRandom.hex}" }
-      let(:project_params) do
-        {
-          template_name: project.name,
-          name: new_project_name,
-          path: new_project_name,
-          use_custom_template: true,
-          group_with_project_templates_id: subgroup.id,
-          namespace_id: subgroup.id
-        }
+
+      context 'using template name' do
+        let(:project_params) do
+          {
+            template_name: project.name,
+            name: new_project_name,
+            path: new_project_name,
+            use_custom_template: true,
+            group_with_project_templates_id: subgroup.id,
+            namespace_id: subgroup.id
+          }
+        end
+
+        it_behaves_like 'creates projects with templates'
       end
 
-      it_behaves_like 'creates projects with templates'
+      context 'using template project ID' do
+        let(:project_params) do
+          {
+            template_project_id: project.id,
+            name: new_project_name,
+            path: new_project_name,
+            use_custom_template: true,
+            group_with_project_templates_id: subgroup.id,
+            namespace_id: subgroup.id
+          }
+        end
+
+        it_behaves_like 'creates projects with templates'
+      end
     end
 
     context 'when importing with mirror attributes' do

lib/api/projects.rb

@@ -71,7 +71,8 @@ module API
         optional :namespace_id, type: Integer, desc: 'Namespace ID for the new project. Default to the user namespace.'
         optional :import_url, type: String, desc: 'URL from which the project is imported'
         optional :template_name, type: String, desc: "Name of template from which to create project"
-        mutually_exclusive :import_url, :template_name
+        optional :template_project_id, type: Integer, desc: "Project ID of template from which to create project"
+        mutually_exclusive :import_url, :template_name, :template_project_id
       end
 
       def load_projects