Основы API

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

• Accept

  Указывает список типов данных, которые сервер может вернуть и которые клиент принимает или способен обработать. Значение должно представлять собой список одного или нескольких MIME-типов, разделённых двоеточиями.

  Для большинства запросов следует указать тип данных JSON (application/json). Для вложений можно явно указать MIME-тип или использовать */*, чтобы указать, что поддерживаются все типы файлов. Если заголовок Accept не указан, предполагается MIME-тип */* (то есть клиент принимает все форматы).

  Использовать Accept в запросах к CouchDB необязательно, но настоятельно рекомендуется: это помогает убедиться, что клиент сможет обработать возвращённые данные.

  Если указать тип данных с помощью заголовка Accept, CouchDB применит указанный тип в возвращаемом поле заголовка Content-type. Например, если явно запросить application/json в Accept запроса, в возвращённых HTTP-заголовках будет использоваться значение поля Content-type.

  Например, при отправке запроса без явно указанного заголовка Accept или при указании */*:

  GET /recipes HTTP/1.1
  Host: couchdb:5984
  Accept: */*

  Возвращаются следующие заголовки:

  HTTP/1.1 200 OK
  Server: CouchDB (Erlang/OTP)
  Date: Thu, 13 Jan 2011 13:39:34 GMT
  Content-Type: text/plain;charset=utf-8
  Content-Length: 227
  Cache-Control: must-revalidate

  Примечание

  Возвращаемый тип содержимого — text/plain, хотя данные, возвращённые запросом, представлены в формате JSON.

  Явное указание заголовка Accept:

  GET /recipes HTTP/1.1
  Host: couchdb:5984
  Accept: application/json

  Среди возвращённых заголовков есть тип содержимого application/json:

  HTTP/1.1 200 OK
  Server: CouchDB (Erlang/OTP)
  Date: Thu, 13 Jan 2013 13:40:11 GMT
  Content-Type: application/json
  Content-Length: 227
  Cache-Control: must-revalidate

• Content-type

  Указывает тип содержимого данных, передаваемых в запросе. Для указания используются MIME-типы. Для большинства запросов это будет JSON (application/json). Для некоторых параметров MIME-типом будет обычный текст. При загрузке вложений следует указать соответствующий MIME-тип вложения или двоичный тип (application/octet-stream).

  Настоятельно рекомендуется указывать Content-type в запросе.

• X-Couch-Request-ID

  (Необязательно) CouchDB добавляет заголовок X-Couch-Request-ID к каждому ответу, чтобы пользователям было проще сопоставить возникшую проблему с журналом CouchDB.

  Если этот заголовок присутствует в запросе (и его значение не превышает 36 символов из набора 0-9a-zA-z-_), это значение будет использоваться внутри системы как nonce запроса, которое отображается в журналах, а также возвращаться в заголовке ответа X-Couch-Request-ID.

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

Сервер возвращает заголовки ответов вместе с содержимым. Они включают различные поля заголовков, многие из которых являются стандартными заголовками HTTP-ответа и не имеют значения для работы CouchDB. Ниже перечислены заголовки ответов, важные для CouchDB.

• Cache-control

  Заголовок HTTP-ответа управления кэшированием содержит рекомендации для механизмов кэширования клиента о том, как обрабатывать возвращённые данные. Обычно CouchDB возвращает must-revalidate, указывая, что при возможности данные следует проверить повторно. Это позволяет правильно обновлять динамическое содержимое.

• Content-length

  Длина возвращённого содержимого в байтах.

• Content-type

  Указывает MIME-тип возвращённых данных. Для большинства запросов возвращается MIME-тип text/plain. Весь текст кодируется в Unicode (UTF-8), что явно указывается в возвращённом Content-type как text/plain;charset=utf-8.

• Etag

  Поле HTTP-заголовка Etag используется для указания ревизии документа или представления.

  ETag назначаются группе map/reduce (набору представлений в одном документе дизайна). Любое изменение индексов этих представлений приводит к созданию нового ETag для всех URL представлений в одном документе дизайна, даже если результаты конкретного представления не изменились.

  У каждого URL _view свой ETag, который обновляется только при изменениях базы данных, влияющих на соответствующий индекс. Если индекс этого представления не меняется, у него сохраняется исходный ETag (поэтому ответ 304 - Not Modified отправляется чаще).

• Transfer-Encoding

  Если в ответе используется кодировка, она указывается в этом поле заголовка.

  Transfer-Encoding: chunked означает, что ответ отправляется частями; этот метод называется передачей с фрагментированным кодированием. Он используется, когда CouchDB заранее не знает размер отправляемых данных (например, для ленты изменений).

• X-CouchDB-Body-Time

  Время получения тела запроса в миллисекундах.

  Доступно, если запрос содержит тело.

• X-Couch-Request-ID

  Уникальный идентификатор запроса.

Обработка чисел

Разработчики и пользователи, впервые сталкивающиеся с обработкой чисел на компьютере, часто удивляются, обнаруживая, что число, сохранённое в формате JSON, не обязательно возвращается в точности тем же числом при посимвольном сравнении.

Все числа в JSON, содержащие десятичную точку или экспоненту, обрабатываются виртуальной машиной Erlang как значения типа «double». Все числа, используемые в представлениях, обрабатываются сервером представлений как числа (в распространённом случае JavaScript даже целые числа преобразуются в double, поскольку именно так JavaScript определяет число).

Рассмотрим документ, который мы записываем в CouchDB:

{
    "_id":"30b3b38cdbd9e3a587de9b8122000cff",
    "number": 1.1
}

Теперь прочитаем этот документ из CouchDB:

{
    "_id":"30b3b38cdbd9e3a587de9b8122000cff",
    "_rev":"1-f065cee7c3fd93aa50f6c97acde93030",
    "number":1.1000000000000000888
}

При этом CouchDB меняет текстовое представление результата декодирования переданного значения на представление в некотором числовом формате. В большинстве случаев это число с плавающей точкой двойной точности IEEE 754, которое используют почти все остальные языки.

Отличие Erlang от других языков заключается в том, что он не пытается красиво вывести результат, используя минимальное число символов. Например, именно поэтому выполняется следующее соотношение:

ejson:encode(ejson:decode(<<"1.1">>)).
<<"1.1000000000000000888">>

Может сбить с толку то, что внутри программы оба этих формата декодируются в одно и то же представление IEEE-754. И что ещё важнее, при обработке всеми основными известными нам парсерами они декодируются в достаточно близкое представление.

До сих пор мы рассматривали только случаи изменения текстового представления. Другой важный случай — входное значение содержит больше точности, чем может быть представлено типом double. (Можно утверждать, что в таком случае данные «теряются», если не считать, что числа хранятся в формате double.)

Вот журналы нескольких наиболее распространённых библиотек JSON, установленных на компьютере автора:

Ejson (текущий парсер CouchDB) в CouchDB с sha 168a663b:

$ ./utils/run -i
Erlang R14B04 (erts-5.8.5) [source] [64-bit] [smp:2:2] [rq:2]
[async-threads:4] [hipe] [kernel-poll:true]

Eshell V5.8.5  (abort with ^G)
1> ejson:encode(ejson:decode(<<"1.01234567890123456789012345678901234567890">>)).
<<"1.0123456789012346135">>
2> F = ejson:encode(ejson:decode(<<"1.01234567890123456789012345678901234567890">>)).
<<"1.0123456789012346135">>
3> ejson:encode(ejson:decode(F)).
<<"1.0123456789012346135">>

Node:

$ node -v
v0.6.15
$ node
JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
'1.0123456789012346'
var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
undefined
JSON.stringify(JSON.parse(f))
'1.0123456789012346'

Python:

$ python
Python 2.7.2 (default, Jun 20 2012, 16:23:33)
[GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
import json
json.dumps(json.loads("1.01234567890123456789012345678901234567890"))
'1.0123456789012346'
f = json.dumps(json.loads("1.01234567890123456789012345678901234567890"))
json.dumps(json.loads(f))
'1.0123456789012346'

Ruby:

$ irb --version
irb 0.9.5(05/04/13)
require 'JSON'
=> true
JSON.dump(JSON.load("[1.01234567890123456789012345678901234567890]"))
=> "[1.01234567890123]"
f = JSON.dump(JSON.load("[1.01234567890123456789012345678901234567890]"))
=> "[1.01234567890123]"
JSON.dump(JSON.load(f))
=> "[1.01234567890123]"

Spidermonkey:

$ js -h 2>&1 | head -n 1
JavaScript-C 1.8.5 2011-03-31
$ js
js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
"1.0123456789012346"
js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
js> JSON.stringify(JSON.parse(f))
"1.0123456789012346"

Как видите, все они ведут себя практически одинаково, за исключением Ruby, который, похоже, теряет часть точности по сравнению с другими библиотеками.

Внимательный читатель заметит, что ejson (библиотека JSON CouchDB) вывела ещё три цифры. Может показаться, что это связано с каким-то внутренним различием, но на самом деле это лишь более конкретный вариант входного значения 1.1, описанного выше.

Важно понимать, что double может хранить только конечное число значений. Здесь мы создаём строку, которая при обработке «стандартными» алгоритмами разбора чисел с плавающей точкой (то есть strtod) даст тот же набор битов в памяти, что и исходное значение. Иными словами, байты числа, сериализованного в JSON, выбираются таким образом, чтобы они соответствовали одному конкретному значению, которое может представлять тип double.

Важно понимать, что мы отображаем одно бесконечное множество на конечное. Это легко увидеть, если задуматься над следующим:

1.0 == 1.00 == 1.000 = 1.(infinite zeros)

Очевидно, компьютер не может хранить бесконечное число байтов, поэтому нам приходится сокращать бесконечное множество до конечного, которое можно представить компактно.

Другие библиотеки JSON решают лишь такую задачу:

«Какое минимальное число символов нужно использовать, чтобы выбрать конкретное значение типа double?»

В этой задаче множество тонких нюансов, которые сложно реализовать на C без значительных усилий (Python потребовалось больше года, чтобы разобраться с ней с помощью сложной системы сборки, автоматически запускаемой на нескольких разных архитектурах).

Надеемся, нам удалось показать, что CouchDB не делает ничего «странного», изменяя входные данные. Она работает так же, как любая другая распространённая библиотека JSON, просто не выполняет красивый вывод.

С другой стороны, если вам действительно нужен тип данных для чисел, отличный от double IEEE-754, то, как уже говорилось, не следует передавать числа через это представление. В JSON это можно сделать, закодировав числа как строки или используя целочисленные типы (хотя целочисленные типы тоже могут создать проблемы, если использовать платформу с нестандартным представлением целых чисел, например JavaScript).

Дополнительную информацию можно легко найти, в том числе в руководстве по числам с плавающей точкой и справочнике Дэвида Голдберга.

Кроме того, если кто-то действительно заинтересован в изменении такого поведения, мы будем рады вкладу в jiffy (которая, предположительно, заменит ejson, когда мы обновим систему сборки). В качестве источников вдохновения мы рассматривали TCL и Python. Если вы знаете достойную реализацию этого алгоритма вывода чисел с плавающей точкой, сообщите нам.