Merge branch 'doc_refactor_namespaces_api' into 'master'

Refactor namespaces API documentation



See merge request !2472

doc/api/namespaces.md

 # Namespaces
 
+Usernames and groupnames fall under a special category called namespaces.
+
+For users and groups supported API calls see the [users](users.md) and
+[groups](groups.md) documentation respectively.
+
+[Pagination](README.md#pagination) is used.
+
 ## List namespaces
 
-Get a list of namespaces. (As user: my namespaces, as admin: all namespaces)
+Get a list of the namespaces of the authenticated user. If the user is an
+administrator, a list of all namespaces in the GitLab instance is shown.
 
 ```
 GET /namespaces
 ```
 
+Example request:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces
+```
+
+Example response:
+
 ```json
 [
   {
@@ -23,22 +39,32 @@ GET /namespaces
 ]
 ```
 
-You can search for namespaces by name or path, see below.
-
 ## Search for namespace
 
-Get all namespaces that match your string in their name or path.
+Get all namespaces that match a string in their name or path.
 
 ```
 GET /namespaces?search=foobar
 ```
 
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `search`  | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |
+
+Example request:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter
+```
+
+Example response:
+
 ```json
 [
   {
-    "id": 1,
-    "path": "user1",
-    "kind": "user"
+    "id": 4,
+    "path": "twitter",
+    "kind": "group"
   }
 ]
 ```