4 files changed, 205 insertions, 2 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 8f2a14e825e..89ffe9d7868 100644
--- a/doc/api/README.md
+++ b/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)
diff --git a/doc/api/groups.md b/doc/api/groups.md
index c2daa8bc029..99d200c9c93 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -40,6 +40,38 @@ GET /groups
 ]
 ```
 
+When adding the parameter `statistics=true` and the authenticated user is an admin, additional group statistics are returned.
+
+```
+GET /groups?statistics=true
+```
+
+```json
+[
+  {
+    "id": 1,
+    "name": "Foobar Group",
+    "path": "foo-bar",
+    "description": "An interesting group",
+    "visibility": "public",
+    "lfs_enabled": true,
+    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
+    "web_url": "http://localhost:3000/groups/foo-bar",
+    "request_access_enabled": false,
+    "full_name": "Foobar Group",
+    "full_path": "foo-bar",
+    "parent_id": null,
+    "statistics": {
+      "storage_size" : 212,
+      "repository_size" : 33,
+      "lfs_objects_size" : 123,
+      "job_artifacts_size" : 57
+
+    }
+  }
+]
+```
+
 You can search for groups by name or path, see below.
 
 ## List a group's projects
diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md
new file mode 100644
index 00000000000..51962595e33
--- /dev/null
+++ b/doc/api/pages_domains.md
@@ -0,0 +1,170 @@
+# 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
+```
diff --git a/doc/api/services.md b/doc/api/services.md
index 49b87a4228c..6c8f196fd5c 100644
--- a/doc/api/services.md
+++ b/doc/api/services.md
@@ -478,8 +478,8 @@ PUT /projects/:id/services/jira
 | --------- | ---- | -------- | ----------- |
 | `url`           | string | yes | The URL to the JIRA project which is being linked to this GitLab project, e.g., `https://jira.example.com`. |
 | `project_key`   | string | yes | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. |
-| `username`      | string | no  | The username of the user created to be used with GitLab/JIRA. |
-| `password`      | string | no  | The password of the user created to be used with GitLab/JIRA. |
+| `username`      | string | yes  | The username of the user created to be used with GitLab/JIRA. |
+| `password`      | string | yes  | The password of the user created to be used with GitLab/JIRA. |
 | `jira_issue_transition_id` | integer | no | The ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. |
 
 ### Delete JIRA service