Проблема API-ключей, которые никогда не истекают
Ключ, выданный много лет назад, ни разу не заменённый и до сих пор действующий, это не удобство. Это риск, на который никто не смотрел уже много лет.
Почему качество документации важнее количества функций
Страница с ценами, на которой перечислено сорок эндпоинтов, выглядит солиднее, чем страница с пятнадцатью. Но нередко это ещё и тревожный сигнал. Создание эндпоинта составляет лишь часть работы по тому, чтобы им можно было пользоваться. Остальное это документация: понятные описания параметров, реальные примеры запросов и ответов, честные заметки о пограничных случаях и простое объяснение того, что происходит, когда что-то идёт не так. Пропустите эту работу для сорока эндпоинтов, и вы получите сорок функций, которые технически существуют, а практически почти нет.
Мы предпочитаем меньше хорошо задокументированных вещей, чем больше плохо задокументированных. Разработчик, оценивающий API, редко начинает со списка функций. Он читает документацию, пробует пример запроса и в первые же минуты составляет мнение обо всей компании в зависимости от того, работает ли этот пример так, как написано. Если нет, количество функций на маркетинговой странице перестаёт иметь значение, потому что доверие, необходимое, чтобы читать дальше, уже ушло.
Хорошая документация для нас означает несколько конкретных вещей, а не расплывчатое обещание. Это значит, что аутентификация объяснена с понятным показом каждого поддерживаемого способа, а не только того, который предпочитает провайдер. Это значит, что лимиты запросов указаны реальными числами, а не фразой «действуют щедрые лимиты». Это значит, что коды ошибок перечислены вместе с тем, что на самом деле вызывает каждый из них, чтобы разработчик, отлаживающий неудачный запрос, мог найти ответ в документации, а не гадать по одному лишь коду статуса. Ничего из этого не требует дополнительной разработки. Это требует, чтобы кто-то решил, что ясно всё записать не является необязательной рутиной, прилагаемой к настоящему продукту.
У документации, которая всего лишь сносная, есть и накапливающаяся цена. Разработчик, не нашедший ответа в документации, создаёт обращение в поддержку, и теперь решение одного этого вопроса стоит времени сотрудников в дополнение к времени разработчиков, уже потраченному на создание функции. Умножьте это на достаточное число клиентов, споткнувшихся об один и тот же непонятный абзац, и «экономия» от скудной документации быстро становится отрицательной. Понятная документация не приятное дополнение поверх API. Она дешевле альтернативы, если учесть нагрузку на поддержку, которую порождает непонятный абзац.
Мы также считаем, что качество документации один из немногих сигналов, которые потенциальный клиент действительно может оценить, прежде чем браться за интеграцию. Историю доступности провайдера за пять минут легко не проверишь, а точность данных нельзя полностью оценить, не интегрировавшись сначала. Зато за пять минут можно прочитать документацию и понять, достаточно ли хорошо компания, которая её написала, понимала продукт, чтобы объяснить его просто, или документация выглядит как запоздалая мысль, прикрученная к списку функций, созданному для страницы продаж.
Длинный список функций написать легко. Документацию, по которой разработчик может построить интеграцию с первой попытки, нет, и именно эта разница делает её важнее.