Коллеги, как вы думаете, что должно включать в себя описание метода в api? Должны ли описываться условия, при которых выполняется та или иная команда?

Думаю, зависит от API, для кого оно, какие задачи можно решить, как у вас выстроена документация и т. д.

Мы коротко описываем, что делает метод, и указываем ограничения (например, если метод нужен только определенной категории пользователей).
Но у нас есть API reference и отдельные инструкции, как решать с помощью API ту или иную задачу.

А у нас нет. У нас вообще ни черта нет. Я предлагаю дописать API. Написать, когда используется тот или иной метод. А не просто описание параметров и пример запроса. Но разработчик думает по-другому)

Аналогично )

Я правильно понимаю, что сейчас просто перечень методов, у каждого метода есть только название, описание параметров и пример запроса (и ответа?)?
Если да, то почему разработчик считает, что этого достаточно? Чем аргументирует? В чём его интерес оставить так, как есть?

И это внутренний API Или внешний, для ваших пользователей?

Разработчики вообще мало когда хотят документацию сразу) у них на всё универсальный вопрос "а нафига? В код посмотрел да всё понял". На что должен быть универсальный ответ "документация нужна не только вам и не только сейчас, а на будущее". Вековое противостояние такое

При этом сами разработчики читают чужую документацию на API, и сетуют, если она плохая )

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

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

отправляет мне из википедии определения API, видимо, для него API и Описание API - одно и то же

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

ну и в этом "описании" есть методы, с разными заголовками, разными параметрами, но одинаковым дескрипшн. На вопрос "в чем отличие?" автор этой апишки отвечает, что: апи не отвечает на вопрос когда какой метод вызывается. апи отвечает на вопрос как вызвать тот или иной метод, с какими параметрами и что будет при этом выполнено. принтер не знает ничего о работе кассы и не должен. называется инкапсуляция. запихивать инфу о кассе в инфу о принтере неверно

Он, вообще говоря, прав. Вы пишете про интерфейс принтера или про сценарий взаимодействия касса-принтер?

про взаимодействие кассы и принтера.

Тогда это все же не совсем описание API, мне кажется.

Так а что по вашему описание API?

Как я понимаю, это, условно, API принтера, которые решает задачи кассы.
На мой взгляд, из документации должно быть понятно, какие задачи пользователя (кассы) умеет решать API и как это делать, в какой последовательности дёргать ручки и с какими параметрами.

В таких штуках есть да, перечень операций, описание входных-выходных парамтеров и неприятностей, которые могут случиться.

Ну и краткое описание того, что операция, собственно, делает.