• ↓
  • ↑
  • ⇑
 
Записи пользователя: Ri (список заголовков)
15:43 

Система версий

Ri
И тесно облакам.
Как я и предсказывал, начались проблемы с совместимостью. Предлагаю следующую реализацию.

Код каждой версии API хранится на сервере в отдельной папке. Если нужно что-то поменять в API, код текущей версии не меняется, вместо этого создается новая папка. Исключение нужно сделать только для уязвимостей, которые нужно чинить и во всех предыдущих версиях.

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

Если происходят какие-то другие изменения в проекте (например, изменения структуры БД), нужно следить за тем, чтобы старые версии не ломались. Желательно сделать автоматические тесты всех имеющихся версий API и запускать эти тесты регулярно.

Для версий API устанавливается срок жизни, в течение которого они будут работать, даже если выходят новые версии API. Этот срок должен быть достаточно большим, чтобы разработчики успели обновить приложения. (Прошу в комментариях написать, кому какого срока достаточно.) С другой стороны, если нет необходимости удалять старую версию, то лучше этого не делать даже после того, как ее срок действия закончился. Когда API будет отшлифовано, нужно будет периодически делать версии API с долгосрочной поддержкой.

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

Для упрощения реализации в качестве версии лучше использовать обычное целое число. Для указания версии API можно выбрать один из следующих способов:

1) Передавать version=42 в качестве одного из GET- или POST-параметров. Этот способ более красивый.

2) В качестве URL для доступа к API использовать www.diary.ru/api/version42/?method=... Я бы предпочел этот способ, так как он более надежный. Не нужно делать общую точку входа для всех версий. Каждая версия будет просто храниться в папке versionN. В таком варианте меньше вероятность, что изменения в коде одной из версий как-то повлияют на остальные версии.

Если запрошенная версия не поддерживается, нужно отдавать клиенту сообщение об этом (во втором варианте реализации достаточно ошибки 404). Если версия не указана, то используется та версия, которая использовалась в момент введения системы версий.

@темы: Тип: Предложение, Статус: не исправлено, Важность: 3 (Major)

04:11 

Обеспечить совместимость параметров post.get, post.create, post.update

Ri
И тесно облакам.
Сейчас наблюдается полнейшая неразбериха в параметрах этих методов. Одни и те же вещи там выдаются (или передаются) по-разному. Примеров масса:

- close_access_mode и close_access_mode2 против access
- poll_answer_x против poll_src.answer
- no_comments против no_comment

Нужно сделать так, чтобы в post.get можно было получить всю информацию, необходимую для обновления записи в post.update без потери данных. Сейчас некоторых параметров просто нет, а с другими приходится извращаться: access приходится вручную разделять на close_access_mode и close_access_mode2 с помощью сравнения с 10, для poll_src.answer приходится итерироваться и переделывать структуру данных. Полезность API в таком случае кажется сомнительной. Дайте возможность просто взять и отредактировать запись. Это же такая простая задача. Откуда такие безумные параметры?

@темы: Статус: решено, Важность: 3 (Major), post.update, post.get, post.create, Тип: Неудобство

04:00 

Режим совместимости

Ri
И тесно облакам.
Если я не ошибаюсь, раньше в post.update можно было не указывать уровень доступа, и он просто не менялся. Сейчас, если его не указать, запись становится открытой. Есть еще некоторые параметры, которых нет в API, например, альтернативный текст закрытой записи. Если он будет позже добавлен и сделан обязательным, то придется обновить код, иначе либо всё сломается, либо альтернативный текст будет просто удаляться, что нехорошо.

Будет ли поддерживаться обратная совместимость? Если нет, то необходимо дать возможность указывать, какую версию API использует приложение, и поддерживать предыдущие версии API хотя бы некоторое время.

@темы: Важность: 3 (Major), Тип: Предложение

03:53 

Варианты ответов к опросу

Ri
И тесно облакам.
В документации написано, что варианты указываются с помощью параметров poll_answer_{0..9}. Фактически используются параметры poll_answer_{1..10}. Нужно поправить или там, или там.

@темы: post.update, Статус: решено, Тип: Ошибка

17:46 

Самопроизвольное удаление голосования в post.update

Ri
И тесно облакам.
Если в post.update не передать никаких параметров, связанных с голосованием, то имеющееся голосование удаляется. Поскольку в API нет возможности получить имеющееся голосования, то попытка отредактировать запись с голосованием с помощью любого приложения, использующего API, приведет к потере данных. Нужно сделать следующее:

1. post.update не должен изменять состояние голосования, если никаких параметров не передано.
2. Если в post.update передан пустой текст записи и не переданы параметры голосования, но в записи уже присутствует голосование, не выдавать ошибку "вы не ввели текст записи", а сохранять остальные переданные параметры (например, теги).
3. В ответ post.get нужно добавить информацию о голосовании.

@API

главная