BigW Consortium Gitlab

namespaces.md 1.73 KB
Newer Older
1
# Namespaces API
2

3 4 5 6
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.
7 8 9

[Pagination](README.md#pagination) is used.

10 11
## List namespaces

12 13
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.
14 15 16 17 18

```
GET /namespaces
```

19 20
Example request:

21
```bash
22
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces
23 24
```

25 26
Example response:

27 28 29 30 31
```json
[
  {
    "id": 1,
    "path": "user1",
32
    "kind": "user",
33
    "full_path": "user1"
34 35 36 37
  },
  {
    "id": 2,
    "path": "group1",
38 39 40
    "kind": "group",
    "full_path": "group1",
    "parent_id": "null",
41
    "members_count_with_descendants": 2
42 43 44 45 46 47
  },
  {
    "id": 3,
    "path": "bar",
    "kind": "group",
    "full_path": "foo/bar",
48
    "parent_id": "9",
49
    "members_count_with_descendants": 5
50 51 52 53
  }
]
```

54 55
**Note**: `members_count_with_descendants` are presented only for group masters/owners.

56 57
## Search for namespace

58
Get all namespaces that match a string in their name or path.
59 60 61 62 63

```
GET /namespaces?search=foobar
```

64 65 66 67
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `search`  | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |

68 69
Example request:

70
```bash
71
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces?search=twitter
72 73
```

74 75
Example response:

76 77 78
```json
[
  {
79 80
    "id": 4,
    "path": "twitter",
81 82
    "kind": "group",
    "full_path": "twitter",
83
    "parent_id": "null",
84
    "members_count_with_descendants": 2
85 86 87
  }
]
```