Merge branch '23000-pages-api' into 'master'

Resolve "Pages API"

Closes #23000

See merge request gitlab-org/gitlab-ce!13917

app/models/pages_domain.rb

@@ -16,9 +16,9 @@ class PagesDomain < ActiveRecord::Base
     key: Gitlab::Application.secrets.db_key_base,
     algorithm: 'aes-256-cbc'
 
-  after_create :update
-  after_save :update
-  after_destroy :update
+  after_create :update_daemon
+  after_save :update_daemon
+  after_destroy :update_daemon
 
   def to_param
     domain
@@ -80,7 +80,7 @@ class PagesDomain < ActiveRecord::Base
 
   private
 
-  def update
+  def update_daemon
     ::Projects::UpdatePagesConfigurationService.new(project).execute
   end
 

changelogs/unreleased/23000-pages-api.yml

+---
+title: Add API endpoints for Pages Domains
+merge_request: 13917
+author: Travis Miller
+type: added

doc/api/README.md

@@ -37,6 +37,7 @@ following locations:
 - [Notes](notes.md) (comments)
 - [Notification settings](notification_settings.md)
 - [Open source license templates](templates/licenses.md)
+- [Pages Domains](pages_domains.md)
 - [Pipelines](pipelines.md)
 - [Pipeline Triggers](pipeline_triggers.md)
 - [Pipeline Schedules](pipeline_schedules.md)

doc/api/pages_domains.md

+# Pages domains API
+
+Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/features/pages/).
+
+The GitLab Pages feature must be enabled to use these endpoints. Find out more about [administering](../administration/pages/index.md) and [using](../user/project/pages/index.md) the feature.
+
+## List pages domains
+
+Get a list of project pages domains. The user must have permissions to view pages domains.
+
+```http
+GET /projects/:id/pages/domains
+```
+
+| Attribute | Type           | Required | Description                              |
+| --------- | -------------- | -------- | ---------------------------------------- |
+| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains
+```
+
+```json
+[
+  {
+    "domain": "www.domain.example",
+    "url": "http://www.domain.example"
+  },
+  {
+    "domain": "ssl.domain.example",
+    "url": "https://ssl.domain.example",
+    "certificate": {
+      "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
+      "expired": false,
+      "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
+      "certificate_text": "Certificate:\n … \n"
+    }
+  }
+]
+```
+
+## Single pages domain
+
+Get a single project pages domain. The user must have permissions to view pages domains.
+
+```http
+GET /projects/:id/pages/domains/:domain
+```
+
+| Attribute | Type           | Required | Description                              |
+| --------- | -------------- | -------- | ---------------------------------------- |
+| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `domain`  | string         | yes      | The domain                               |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example
+```
+
+```json
+{
+  "domain": "www.domain.example",
+  "url": "http://www.domain.example"
+}
+```
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
+```
+
+```json
+{
+  "domain": "ssl.domain.example",
+  "url": "https://ssl.domain.example",
+  "certificate": {
+    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
+    "expired": false,
+    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
+    "certificate_text": "Certificate:\n … \n"
+  }
+}
+```
+
+## Create new pages domain
+
+Creates a new pages domain. The user must have permissions to create new pages domains.
+
+```http
+POST /projects/:id/pages/domains
+```
+
+| Attribute     | Type           | Required | Description                              |
+| ------------- | -------------- | -------- | ---------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `domain`      | string         | yes      | The domain                               |
+| `certificate` | file/string    | no       | The certificate in PEM format with intermediates following in most specific to least specific order.|
+| `key`         | file/string    | no       | The certificate key in PEM format.       |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="domain=ssl.domain.example" --form="certificate=@/path/to/cert.pem" --form="key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains
+```
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="domain=ssl.domain.example" --form="certificate=$CERT_PEM" --form="key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains
+```
+
+```json
+{
+  "domain": "ssl.domain.example",
+  "url": "https://ssl.domain.example",
+  "certificate": {
+    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
+    "expired": false,
+    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
+    "certificate_text": "Certificate:\n … \n"
+  }
+}
+```
+
+## Update pages domain
+
+Updates an existing project pages domain. The user must have permissions to change an existing pages domains.
+
+```http
+PUT /projects/:id/pages/domains/:domain
+```
+
+| Attribute     | Type           | Required | Description                              |
+| ------------- | -------------- | -------- | ---------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `domain`      | string         | yes      | The domain                               |
+| `certificate` | file/string    | no       | The certificate in PEM format with intermediates following in most specific to least specific order.|
+| `key`         | file/string    | no       | The certificate key in PEM format.       |
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="certificate=@/path/to/cert.pem" --form="key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
+```
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="certificate=$CERT_PEM" --form="key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
+```
+
+```json
+{
+  "domain": "ssl.domain.example",
+  "url": "https://ssl.domain.example",
+  "certificate": {
+    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
+    "expired": false,
+    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
+    "certificate_text": "Certificate:\n … \n"
+  }
+}
+```
+
+## Delete pages domain
+
+Deletes an existing project pages domain.
+
+```http
+DELETE /projects/:id/pages/domains/:domain
+```
+
+| Attribute | Type           | Required | Description                              |
+| --------- | -------------- | -------- | ---------------------------------------- |
+| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `domain`  | string         | yes      | The domain                               |
+
+```bash
+curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
+```

lib/api/api.rb

@@ -131,6 +131,7 @@ module API
     mount ::API::Namespaces
     mount ::API::Notes
     mount ::API::NotificationSettings
+    mount ::API::PagesDomains
     mount ::API::Pipelines
     mount ::API::PipelineSchedules
     mount ::API::ProjectHooks

lib/api/entities.rb

@@ -1043,5 +1043,22 @@ module API
       expose :key
       expose :value
     end
+
+    class PagesDomainCertificate < Grape::Entity
+      expose :subject
+      expose :expired?, as: :expired
+      expose :certificate
+      expose :certificate_text
+    end
+
+    class PagesDomain < Grape::Entity
+      expose :domain
+      expose :url
+      expose :certificate,
+             if: ->(pages_domain, _) { pages_domain.certificate? },
+             using: PagesDomainCertificate do |pages_domain|
+        pages_domain
+      end
+    end
   end
 end

lib/api/helpers.rb

@@ -184,6 +184,10 @@ module API
       end
     end
 
+    def require_pages_enabled!
+      not_found! unless user_project.pages_available?
+    end
+
     def can?(object, action, subject = :global)
       Ability.allowed?(object, action, subject)
     end

lib/api/pages_domains.rb

+module API
+  class PagesDomains < Grape::API
+    include PaginationParams
+
+    before do
+      authenticate!
+      require_pages_enabled!
+    end
+
+    after_validation do
+      normalize_params_file_to_string
+    end
+
+    helpers do
+      def find_pages_domain!
+        user_project.pages_domains.find_by(domain: params[:domain]) || not_found!('PagesDomain')
+      end
+
+      def pages_domain
+        @pages_domain ||= find_pages_domain!
+      end
+
+      def normalize_params_file_to_string
+        params.each do |k, v|
+          if v.is_a?(Hash) && v.key?(:tempfile)
+            params[k] = v[:tempfile].to_a.join('')
+          end
+        end
+      end
+    end
+
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
+    resource :projects, requirements: { id: %r{[^/]+} } do
+      desc 'Get all pages domains' do
+        success Entities::PagesDomain
+      end
+      params do
+        use :pagination
+      end
+      get ":id/pages/domains" do
+        authorize! :read_pages, user_project
+
+        present paginate(user_project.pages_domains.order(:domain)), with: Entities::PagesDomain
+      end
+
+      desc 'Get a single pages domain' do
+        success Entities::PagesDomain
+      end
+      params do
+        requires :domain, type: String, desc: 'The domain'
+      end
+      get ":id/pages/domains/:domain", requirements: { domain: %r{[^/]+} } do
+        authorize! :read_pages, user_project
+
+        present pages_domain, with: Entities::PagesDomain
+      end
+
+      desc 'Create a new pages domain' do
+        success Entities::PagesDomain
+      end
+      params do
+        requires :domain, type: String, desc: 'The domain'
+        optional :certificate, allow_blank: false, types: [File, String], desc: 'The certificate'
+        optional :key, allow_blank: false, types: [File, String], desc: 'The key'
+        all_or_none_of :certificate, :key
+      end
+      post ":id/pages/domains" do
+        authorize! :update_pages, user_project
+
+        pages_domain_params = declared(params, include_parent_namespaces: false)
+        pages_domain = user_project.pages_domains.create(pages_domain_params)
+
+        if pages_domain.persisted?
+          present pages_domain, with: Entities::PagesDomain
+        else
+          render_validation_error!(pages_domain)
+        end
+      end
+
+      desc 'Updates a pages domain'
+      params do
+        requires :domain, type: String, desc: 'The domain'
+        optional :certificate, allow_blank: false, types: [File, String], desc: 'The certificate'
+        optional :key, allow_blank: false, types: [File, String], desc: 'The key'
+      end
+      put ":id/pages/domains/:domain", requirements: { domain: %r{[^/]+} } do
+        authorize! :update_pages, user_project
+
+        pages_domain_params = declared(params, include_parent_namespaces: false)
+
+        # Remove empty private key if certificate is not empty.
+        if pages_domain_params[:certificate] && !pages_domain_params[:key]
+          pages_domain_params.delete(:key)
+        end
+
+        if pages_domain.update(pages_domain_params)
+          present pages_domain, with: Entities::PagesDomain
+        else
+          render_validation_error!(pages_domain)
+        end
+      end
+
+      desc 'Delete a pages domain'
+      params do
+        requires :domain, type: String, desc: 'The domain'
+      end
+      delete ":id/pages/domains/:domain", requirements: { domain: %r{[^/]+} } do
+        authorize! :update_pages, user_project
+
+        status 204
+        pages_domain.destroy
+      end
+    end
+  end
+end

spec/fixtures/api/schemas/public_api/v4/pages_domains.json

+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "domain": { "type": "string" },
+      "url": { "type": "uri" },
+      "certificate": {
+        "type": "object",
+        "properties": {
+          "subject": { "type": "string" },
+          "expired": { "type": "boolean" },
+          "certificate": { "type": "string" },
+          "certificate_text": { "type": "string" }
+        },
+        "required": ["subject", "expired"],
+        "additionalProperties": false
+      }
+    },
+    "required": ["domain", "url"],
+    "additionalProperties": false
+  }
+}