У меня есть задача объяснить концепцию RESTful API человеку с практически нулевым бэкграундом в Computer Science.
Как рассказать, что такое API, я придумал, теперь мне надо придумать, как объяснить важность документации на такой API.
Хочется донести мысль, что документация на API — абсолютно обязательный предмет: без нее разработчик, каким бы умным он ни был, физически не сможет пользоваться API.
Какую аналогию из реального мира можно было бы взять для такого объяснения?
отправка письма на почте, письмо нужно подписать, указать адрес (эндпойнт) и все элементы адреса, город, улица, квартира, индекс (обязательные параметры), способ отправки (аналогия с методом), наклеить марку с нужной ценой и в нужный угол конверта, иногда - описать содержимое (тело запроса), еще иногда письма бывают с уведомлением о вручении (ответ сервера), все эти правила - такой же контракт, не написал индекс или не знаешь его - письмо будет идти дольше или не дойдет вовсе, также, если у адресата поменялся адрес или цена марки до пункта назначения - а ты не знаешь об этом, писбмо не дойдет