1 files changed, 68 insertions, 2 deletions
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index 4ad6071a0ed..1f0dc700640 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -28,23 +28,34 @@ Example response:
 [
   {
     "id": 1,
+    "name": "user1",
     "path": "user1",
-    "kind": "user"
+    "kind": "user",
+    "full_path": "user1"
   },
   {
     "id": 2,
+    "name": "group1",
     "path": "group1",
-    "kind": "group"
+    "kind": "group",
+    "full_path": "group1",
+    "parent_id": null,
+    "members_count_with_descendants": 2
   },
   {
     "id": 3,
+    "name": "bar",
     "path": "bar",
     "kind": "group",
     "full_path": "foo/bar",
+    "parent_id": 9,
+    "members_count_with_descendants": 5
   }
 ]
 ```
 
+**Note**: `members_count_with_descendants` are presented only for group masters/owners.
+
 ## Search for namespace
 
 Get all namespaces that match a string in their name or path.
@@ -69,9 +80,64 @@ Example response:
 [
   {
     "id": 4,
+    "name": "twitter",
     "path": "twitter",
     "kind": "group",
     "full_path": "twitter",
+    "parent_id": null,
+    "members_count_with_descendants": 2
   }
 ]
 ```
+
+## Get namespace by ID
+
+Get a namespace by ID.
+
+```
+GET /namespaces/:id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer/string | yes | ID or path of the namespace |
+
+Example request:
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces/2
+```
+
+Example response:
+
+```json
+{
+  "id": 2,
+  "name": "group1",
+  "path": "group1",
+  "kind": "group",
+  "full_path": "group1",
+  "parent_id": null,
+  "members_count_with_descendants": 2
+}
+```
+
+Example request:
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces/group1
+```
+
+Example response:
+
+```json
+{
+  "id": 2,
+  "name": "group1",
+  "path": "group1",
+  "kind": "group",
+  "full_path": "group1",
+  "parent_id": null,
+  "members_count_with_descendants": 2
+}
+```