+++
title = "API папки HTTP"
description = "HTTP API папки сбора Harvest"
keywords = ["harvest", "http", "documentation", "api", "folder"]
aliases = ["/docs/harvest/latest/http_api/folder/"]
+++

# API папок

## Идентификатор (id) против уникального идентификатора (uid)

Идентификатор (id) папки представляет собой автоматически увеличивающееся числовое значение и уникален только для каждой установки Harvest.

Уникальный идентификатор (uid) папки может использоваться для уникальной идентификации папок между несколькими установками Harvest. Он генерируется автоматически, если не указан при создании папки. Uid позволяет иметь согласованные URL-адреса для доступа к папкам и при синхронизации папок между несколькими установками Harvest. Это означает, что изменение названия папки не приведет к нарушению каких-либо ссылок с закладками на эту папку.

Идентификатор пользователя может иметь максимальную длину 40 символов.

## Примечание об общей папке

Общая папка (id = 0) является специальной и не является частью API папок, что означает
, что вы не можете использовать этот API для получения информации об общей папке.

## Получить все папки

`GET /api/folders`

Возвращает все папки, на просмотр которых у прошедшего проверку пользователя есть разрешение. Вы можете управлять максимальным количеством возвращаемых папок с помощью параметра запроса `limit`, значение по умолчанию равно 1000.

**Пример Запроса**:

```http
GET /api/folders?limit=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Пример Ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "uid": "nErXDvCkzz",
    "title": "Department ABC"
  },
  {
    "id":2,
    "uid": "k3S1cklGk",
    "title": "Department RND"
  }
]
```

## Получить папку по uid

`GET /api/folders/:uid`

Вернет папку с заданным идентификатором папки.

**Пример Запроса**:

```http
GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Пример Ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}
```

Коды состояния:

- **200** – Найденный
- **401** – Несанкционированный
- **403** – Доступ запрещен
- **404** – Папка не найдена

## Создать папку

`POST /api/folders`

Создает новую папку.

**Пример Запроса**:

```http
POST /api/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "nErXDvCkzz",
  "title": "Department ABC"
}
```

Схема тела JSON:

- **uid** – Необязательно [уникальный идентификатор](/http_api/folder/#identifier-id-vs-unique-identifier-uid).
- **заголовок** – название папки.

**Пример Ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}
```

Коды состояния:

- **200** – Созданный
- **400** – Ошибки (недопустимый json, отсутствующие или недопустимые поля и т.д.)
- **401** – Несанкционированный
- **403** – Доступ запрещен

## Обновить папку

`PUT /api/folders/:uid`

Updates an existing folder identified by uid.

**Пример Запроса**:

```http
PUT /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "title":"Department DEF",
  "version": 1
}
```

Схема тела JSON:

- **uid** – Укажите другой [уникальный идентификатор] (/http_api/folder/#identifier-id-vs-unique-identifier-uid), чем сохраненный, чтобы изменить уникальный идентификатор.
- **заголовок** – название папки.
- ** версия ** – Укажите текущую версию, чтобы иметь возможность обновлять папку. Не требуется, если `overwrite=true`.
- ** перезапись ** – Установите значение true, если вы хотите перезаписать существующую папку более новой версией.

**Пример Ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department DEF",
  "url": "/dashboards/f/nErXDvCkzz/department-def",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}
```

Коды состояния:

- **200** – Обновленный
- **400** – Ошибки (недопустимый json, отсутствующие или недопустимые поля и т.д.)
- **401** – Несанкционированный
- **403** – Доступ запрещен
- **404** – Папка не найдена
- **412** – Предварительное условие не выполнено

В **412** код состояния используется для объяснения того, что вы не можете обновить папку и почему.
Для этого могут быть разные причины:

- Папка была изменена кем-то другим, `статус=версия-несоответствие`

 Тело ответа будет обладать следующими свойствами:

```http
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

{
  "message": "The folder has been changed by someone else",
  "status": "version-mismatch"
}
```

## Удалить папку

`DELETE /api/folders/:uid`

Удаляет существующую папку, идентифицируемую uid, вместе со всеми информационными панелями, хранящимися в папке, если таковые имеются. Эта операция не может быть отменена.

**Пример Запроса**:

```http
DELETE /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

```

**Пример Ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

{
  "message":"Folder deleted",
  "id": 2
}
```

Коды состояния:

- **200** – Удалено
- **401** – Несанкционированный
- **403** – Доступ запрещен
- **404** – Папка не найдена

## Получить папку по идентификатору

`GET /api/folders/id/:id`

Вернет папку, идентифицированную по идентификатору.

**Пример Запроса**:

```http
GET /api/folders/id/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Пример Ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}
```

Коды состояния:

- **200** – Найденный
- **401** – Несанкционированный
- **403** – Доступ запрещен
- **404** – Папка не найдена
