Особенности разработки API: какой API является хорошим?

[Odrin]

Где-то года три назад мы решили выпустить мажорную версию API 2.1

Версия API 2.0 она была очень старая

Почему вы называете минорную версию мажорной?

[mapron]

Потому что они не используют SemVer, и это их право? да, это слегка так непривычно, но это не значит что это незаконно)

[Odrin]

Я ни в коем случае не считаю, что это незаконно. Просто при прочтении возник диссонанс и стало действительно интересно, почему так.

[forgotten]

Потому что система версионирования API Яндекс.Карт (в которой вторая цифра означает обратно несовместимые изменения) на год старше семвера.

[Odrin]

Погуглил немного и нашел ответ на свой вопрос. Действительно, у Яндекс.Карт своя система версионирования, несколько отличная от semver. Спасибо за небольшую историческую справку.

[nikitasius]

Хороший API — это тот, который не заставляет писать лишнее. Вы используете какой-то метод на API и дальше работаете с данными, и вам не нужно писать страшные условия.

Это в сказке. На деле есть разного рода идиоты, которые видят мир через воткнутые в глаза карандаши и из-за которых и приходится, порой, дописывать "страшные условия" в красивый АПИ.

upd: комментарий со стороны того, кто апи пишет. А не того, кто пишет под апи.
upd#2: тоже много крови.

[flancer]

Вы живёте в страшном мире, коллега. Вас окружают идиоты с торчащими из глаз карандашами и вокруг всё в крови. Сюрненько.

[x-foby]

Понимаю, что нужно в обратную совместимость, но было бы, конечно, просто замечательно увидеть новую версию API, написанную под современные браузеры на современном js. Ждём, надеемся и верим.

Ну и да, документация — это, пожалуй, самое слабое место Яндекс.Карт. Очень многие вещи проще нагуглить, чем найти в документации (я уже молчу про понять).

[vsesh]

Спасибо за фидбек!
Про новую версию апи сказать не могу, так как прямо сейчас уже не так тесно связан API карт. Но я знаю, что где-то полгода назад для старых версий браузеров (все ie кроме 11, opera, старые android) зафризили определенную версию API 2.1
tech.yandex.ru/maps/doc/jsapi/2.1/quick-start/tasks/quick-start-docpage

[glader]

Как лучше оповещать разработчиков, использующих мое АПИ, что версия, которую они используют, скоро помрет?

[x-foby]

По-хорошему иметь параметр, позволяющий разработчику подключаться к АПИ в dev-mode.
Ну и, собственно, в этом режиме выводить ему сообщение.
В случае с JS-АПИ можно при вызове методов, которые, скажем, скоро будут deprecated (ну или всей версии АПИ) выводить в консоль варн об этом.

[Mohave]

Или получить рекомендацию материала, где расписано, как лучше реализовать getFriends.

[lxsmkv]

Я всегда задаю себе вопрос «как ты будешь это использовать?». Т.е. нужно, чтобы в точке использования все было просто. В первую очередь код на стороне клиента должен быть простым и понятным. Поэтому я обычно начинаю с наброска клиентского кода, и если он меня устраивает, он простой и понятный, то из него формируется интерфейс. Нельзя придумывать интерфейс «в вакууме».

У меня был интересный опыт, я затребовал фичу у фреймворка, представил им кусок клиентского кода и сказал: «сделайте так, чтобы это заработало». Удивительно как быстро все было готово, и без ошибок. Никаких совещаний и переписок не понадобилось.

Еще я заметил, что иногда интефейс придумывается исходя не из технической необходимости, а из организационного желания переложить ответственность с одной группы людей на другую. Т.е. кому придется имплементировать логику. Тут нужно быть очень внимательным. Всегда смотреть какие данные действительно нужны. Действительно ли нужен весь список, или достаточно булева значения, для выполнения клиентской задачи. Не пытаются ли вас заставить принимать решения в коде которые вы в принципе не должны принимать. В общем и целом, считаю, чем меньше логики в клиенте тем лучше.

[toto66]

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

[puzzler]

Он или оно :D
«КАКОЙ API является хорошим»?
«API ДОЛЖНО быть простым»