/{db}

HEAD /{db}

Возвращает HTTP-заголовки, содержащие минимальный объем информации об указанной базе данных. Поскольку тело ответа пусто, использование метода HEAD — это легкий способ проверить, существует ли уже база данных.

Параметры:

• db – Имя базы данных

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

• 200 OK – База данных существует

• 404 Не найдено – Запрошенная база данных не найдена

Запрос:

HEAD /test HTTP/1.1
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:27:41 GMT
Server: CouchDB (Erlang/OTP)

GET /{db}

Получает информацию об указанной базе данных.

Параметры:

• db – Имя базы данных

Заголовки запроса:

• Accept –

  • application/json

  • text/plain

Заголовки ответа:

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

Объект JSON ответа:

• cluster.n (number) – Реплики. Количество копий каждого документа.

• cluster.q (number) – Шарды. Количество разделов диапазонов.

• cluster.r (number) – Кворум чтения. Количество согласованных копий документа, которые необходимо прочитать для получения успешного ответа.

• cluster.w (number) – Кворум записи. Количество копий документа, которые необходимо записать для получения успешного ответа.

• compact_running (boolean) – Значение true указывает, что для этой базы данных выполняется уплотнение.

• db_name (string) – Имя базы данных.

• disk_format_version (number) – Версия физического формата, используемого для данных при их хранении на диске.

• doc_count (number) – Количество документов в указанной базе данных.

• doc_del_count (number) – Количество удаленных документов

• instance_start_time (string) – Всегда "0". (Возвращается для обратной совместимости.)

• purge_seq (string) – Непрозрачная строка, описывающая состояние очистки базы данных. Не используйте эту строку для подсчета количества операций очистки.

• sizes.active (number) – Размер актуальных данных в базе данных в байтах.

• sizes.external (number) – Несжатый размер содержимого базы данных в байтах.

• sizes.file (number) – Размер файла базы данных на диске в байтах. Индексы представлений в расчет не включаются.

• update_seq (string) – Непрозрачная строка, описывающая состояние базы данных. Не используйте эту строку для подсчета количества обновлений.

• props.partitioned (boolean) – (необязательно) Если это свойство присутствует и имеет значение true, база данных является секционированной.

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

• 200 OK – Запрос успешно выполнен

• 401 Не авторизован – Неавторизованный запрос к защищенному API

• 403 Доступ запрещен – Недостаточно прав / Слишком много запросов с недействительными учетными данными

• 404 Не найдено – Запрошенная база данных не найдена

Запрос:

GET /receipts HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 258
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:38:57 GMT
Server: CouchDB (Erlang/OTP)

{
    "cluster": {
        "n": 3,
        "q": 8,
        "r": 2,
        "w": 2
    },
    "compact_running": false,
    "db_name": "receipts",
    "disk_format_version": 6,
    "doc_count": 6146,
    "doc_del_count": 64637,
    "instance_start_time": "0",
    "props": {},
    "purge_seq": 0,
    "sizes": {
        "active": 65031503,
        "external": 66982448,
        "file": 137433211
    },
    "update_seq": "292786-g1AAAAF..."
}

PUT /{db}

Создает новую базу данных. Имя базы данных {db} должно соответствовать следующим правилам:

• Имя должно начинаться со строчной буквы (a-z)

• Строчные символы (a-z)

• Цифры (0-9)

• Любой из следующих символов: _, $, (, ), +, - и /.

Если вы знакомы с регулярными выражениями, приведенные выше правила можно записать как ^[a-z][a-z0-9_$()+/-]*$.

Параметры:

• db – Имя базы данных

Параметры запроса:

• q (integer) – Шарды, то есть количество разделов диапазонов. По умолчанию 2, если значение не переопределено в cluster config.

• n (integer) – Реплики. Количество копий базы данных в кластере. По умолчанию 3, если значение не переопределено в cluster config .

• partitioned (boolean) – Создавать ли секционированную базу данных. По умолчанию false.

Заголовки запроса:

• Accept –

  • application/json

  • text/plain

Заголовки ответа:

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

• Location – URI-адрес базы данных

Объект JSON ответа:

• ok (boolean) – Статус операции. Присутствует в случае успеха

• error (string) – Тип ошибки. Присутствует, если код ответа — 4xx

• reason (string) – Описание ошибки. Присутствует, если код ответа — 4xx

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

• 201 Создано – База данных успешно создана (кворум достигнут)

• 202 Принято – Запрос принят (как минимум одним узлом)

• 400 Некорректный запрос – Недопустимое имя базы данных

• 401 Не авторизован – Требуются права администратора сервера CouchDB

• 403 Доступ запрещен – Недостаточно прав / Слишком много запросов с недействительными учетными данными

• 412 Предварительное условие не выполнено – База данных уже существует

Запрос:

PUT /db HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:45 GMT
Location: http://localhost:5984/db
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}

Если повторить тот же запрос к CouchDB, сервер вернет 412, поскольку база данных уже существует:

Запрос:

PUT /db HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 412 Precondition Failed
Cache-Control: must-revalidate
Content-Length: 95
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:16 GMT
Server: CouchDB (Erlang/OTP)

{
    "error": "file_exists",
    "reason": "The database could not be created, the file already exists."
}

Если указано недопустимое имя базы данных, CouchDB вернет ответ с кодом 400:

Запрос:

PUT /_db HTTP/1.1
Accept: application/json
Host: localhost:5984

Запрос:

HTTP/1.1 400 Bad Request
Cache-Control: must-revalidate
Content-Length: 194
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:02:10 GMT
Server: CouchDB (Erlang/OTP)

{
    "error": "illegal_database_name",
    "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
}

DELETE /{db}

Удаляет указанную базу данных, а также все содержащиеся в ней документы и вложения.

Примечание

Чтобы предотвратить случайное удаление базы данных, CouchDB ответит кодом состояния HTTP 400, если URL запроса содержит параметр ?rev=. Это указывает на то, что пользователь намеревался удалить документ, но забыл добавить идентификатор документа в URL.

Параметры:

• db – Имя базы данных

Заголовки запроса:

• Accept –

  • application/json

  • text/plain

Заголовки ответа:

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

Объект JSON ответа:

• ok (boolean) – Статус операции

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

• 200 OK – База данных успешно удалена (кворум достигнут, и база данных удалена как минимум одним узлом)

• 202 Принято – Запрос принят (база данных удалена как минимум одним узлом, кворум еще не достигнут)

• 400 Некорректный запрос – Недопустимое имя базы данных или случайно пропущен идентификатор документа

• 401 Не авторизован – Требуются права администратора сервера CouchDB

• 403 Доступ запрещен – Недостаточно прав / Слишком много запросов с недействительными учетными данными

• 404 Не найдено – База данных не существует или указано недопустимое имя базы данных

Запрос:

DELETE /db HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:54:00 GMT
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}

POST /{db}

Создаёт новый документ в указанной базе данных, используя предоставленную структуру JSON-документа.

Если структура JSON включает поле _id, документ будет создан с указанным идентификатором.

Если поле _id не указано, будет сгенерирован новый уникальный идентификатор в соответствии с настроенным на сервере алгоритмом UUID.

Параметры:

• db – Имя базы данных

Заголовки запроса:

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

Параметры запроса:

• batch (string) – Сохраняет документ в пакетном режиме. Возможные значения: ok. Необязательно

Заголовки ответа:

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

• Location – URI документа

Объект JSON ответа:

• id (string) – Идентификатор документа

• ok (boolean) – Статус операции

• rev (string) – Информация о ревизии

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

• 201 Создано – Документ создан и сохранён на диске

• 202 Принято – Данные документа приняты, но ещё не сохранены на диске

• 400 Неверный запрос – Недопустимое имя базы данных

• 401 Не авторизован – Требуются права на запись

• 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

• 404 Не найдено – База данных не существует

• 409 Конфликт – Документ с таким идентификатором уже существует

Запрос:

POST /db HTTP/1.1
Accept: application/json
Content-Length: 81
Content-Type: application/json

{
    "servings": 4,
    "subtitle": "Delicious with fresh bread",
    "title": "Fish Stew"
}

Ответ:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 95
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
Server: CouchDB (Erlang/OTP)

{
    "id": "ab39fe0993049b84cfa81acd6ebad09d",
    "ok": true,
    "rev": "1-9c65296036141e575d32ba9c034dd3ee"
}

POST /db?batch=ok HTTP/1.1
Accept: application/json
Content-Length: 98
Content-Type: application/json

{
    "_id": "FishStew",
    "servings": 4,
    "subtitle": "Delicious with fresh bread",
    "title": "Fish Stew"
}

HTTP/1.1 202 Accepted
Cache-Control: must-revalidate
Content-Length: 28
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: http://localhost:5984/db/FishStew
Server: CouchDB (Erlang/OTP)

{
    "id": "FishStew",
    "ok": true
}