diff options
Diffstat (limited to 'doc/api/topics.md')
| -rw-r--r-- | doc/api/topics.md | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/api/topics.md b/doc/api/topics.md new file mode 100644 index 00000000000..5e9e1b8fc12 --- /dev/null +++ b/doc/api/topics.md @@ -0,0 +1,190 @@ +--- +stage: Manage +group: Workspace +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Topics API **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.5. + +Interact with project topics using the REST API. + +## List topics + +Returns a list of project topics in the GitLab instance ordered by number of associated projects. + +```plaintext +GET /topics +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| ---------- | ------- | ---------------------- | ----------- | +| `page` | integer | **{dotted-circle}** No | Page to retrieve. Defaults to `1`. | +| `per_page` | integer | **{dotted-circle}** No | Number of records to return per page. Defaults to `20`. | +| `search` | string | **{dotted-circle}** No | Search topics against their `name`. | + +Example request: + +```shell +curl "https://gitlab.example.com/api/v4/topics?search=git" +``` + +Example response: + +```json +[ + { + "id": 1, + "name": "GitLab", + "description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.", + "total_projects_count": 1000, + "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon" + }, + { + "id": 3, + "name": "Git", + "description": "Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.", + "total_projects_count": 900, + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + }, + { + "id": 2, + "name": "Git LFS", + "description": null, + "total_projects_count": 300, + "avatar_url": null + } +] +``` + +## Get a topic + +Get a project topic by ID. + +```plaintext +GET /topics/:id +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ------- | ---------------------- | ------------------- | +| `id` | integer | **{check-circle}** Yes | ID of project topic | + +Example request: + +```shell +curl "https://gitlab.example.com/api/v4/topics/1" +``` + +Example response: + +```json +{ + "id": 1, + "name": "GitLab", + "description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.", + "total_projects_count": 1000, + "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon" +} +``` + +## List projects assigned to a topic + +Use the [Projects API](projects.md#list-all-projects) to list all projects assigned to a specific topic. + +```plaintext +GET /projects?topic=<topic_name> +``` + +## Create a project topic + +Create a new project topic. Only available to administrators. + +```plaintext +POST /topics +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| ------------- | ------- | ---------------------- | ----------- | +| `name` | string | **{check-circle}** Yes | Name | +| `avatar` | file | **{dotted-circle}** No | Avatar | +| `description` | string | **{dotted-circle}** No | Description | + +Example request: + +```shell +curl --request POST \ + --data "name=topic1" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/topics" +``` + +Example response: + +```json +{ + "id": 1, + "name": "topic1", + "description": null, + "total_projects_count": 0, + "avatar_url": null +} +``` + +## Update a project topic + +Update a project topic. Only available to administrators. + +```plaintext +PUT /topics/:id +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| ------------- | ------- | ---------------------- | ------------------- | +| `id` | integer | **{check-circle}** Yes | ID of project topic | +| `avatar` | file | **{dotted-circle}** No | Avatar | +| `description` | string | **{dotted-circle}** No | Description | +| `name` | string | **{dotted-circle}** No | Name | + +Example request: + +```shell +curl --request PUT \ + --data "name=topic1" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/topics/1" + + +Example response: + +```json +{ + "id": 1, + "name": "topic1", + "description": null, + "total_projects_count": 0, + "avatar_url": null +} +``` + +### Upload a topic avatar + +To upload an avatar file from your file system, use the `--form` argument. This argument causes +cURL to post data using the header `Content-Type: multipart/form-data`. The +`file=` parameter must point to a file on your file system and be preceded by +`@`. For example: + +```shell +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/topics/1" \ + --form "avatar=@/tmp/example.png" +``` |