Первоначально найдено на https://notecanvas.com/content/blog/are_you_a_victim_of_terrible_api_documentation_/1095

Вас когда-нибудь раздражала документация по API?

Вы когда-нибудь хотели разбить свой монитор из-за разочарования от работы с API?

Вы когда-нибудь часами искали конкретные случаи, в которых конечная точка API, которую вы тестируете, получает какую-то недокументированную ошибку?

Если что-то из вышеперечисленного относится к вам, то вы, вероятно, стали жертвой дрянной реализации API!

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

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

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

Заповеди

Без лишних слов, вот список правил, которым нужно следовать:

  • Ты не должен…. выдавать расплывчатые сообщения об ошибках
    Чаще всего люди, которые тестируют ваш API, сталкиваются с ошибками, особенно если для какой-либо одной конечной точки API используется множество различных тестовых случаев.
    Раздача соответствующие сообщения об ошибках помогают разработчику тестирования понять, в чем заключается его ошибка. Иногда это может быть разработчик; иногда это может быть бэкенд, получающий исключение из-за чего-то, что не было учтено в документации. Тем не менее, выдача правильного сообщения об ошибке помогает разработчику понять, в чем проблема и как предотвратить ее появление в будущем.
    Более того, коды ошибок должны быть точными и соответствовать соглашениям. по кодам ошибок, как указано здесь. Некоторые примеры:
    100 Продолжить
    200 ОК
    201 Создано
    202 Принято
    400 Неверный запрос
    401 Несанкционировано
    500 Внутренняя ошибка сервера
    501 Не реализовано
  • Ты должен…. дать четкое представление о доступе/привилегиях в зависимости от типа пользователя (или типа группы)
    Посмотрите на вас, Microsoft Graph Documentations.
    Позвольте мне рассказать личную историю. Когда я впервые начал использовать Microsoft Graph (ветвь API Microsoft Teams), мне потребовалось около часа, чтобы выяснить, что личные учетные записи (то есть созданные не Microsoft Business) не могут использовать почти все конечные точки API Microsoft Graph. . Единственная причина, по которой я узнал об этом, — это когда я увидел список разрешений и понял, что так было практически со всеми остальными конечными точками.

Подробнее на https://notecanvas.com/content/blog/are_you_a_victim_of_terrible_api_documentation_/1095