API - Application Programming Interface, проще говоря - интерфейс. Во фронте мы часто называем сетевой протокол прикладного уровня API, но термин это общий. Библиотеки имеют API - схему (типы) взаимодействия с помощью какого-то языка программирования (ЯП) и семантику. ЯП имеет API - синтаксис (матчинг текста на абстракции) и семантику.
Семантика - это логика работы в тех или иных условиях. Хорошим примером может выступать принцип идемпотентности, но это не то что каждый может понять сходу, поговорим сначала о синтаксисе.
Синтаксис - самая простая вещь в API, потому что сам по себе он не выражает сложность, максимум - насыщенность и вариативность, а как оно работает - это уже семантика. Синтаксис, можно сказать, имеет константную сложность, зависящую только от его размера (токены, ключевые слова, правила их расстановки). Синтаксис JSON, CSS, HTML достаточно прост, а синтакс OCaml и JavaScript намного сложнее.
Небольшой пример. Стрелочные функции в JS имеют свой синтаксис, но то как работает в них и в обычных функциях this - это семантика.
Так как сложность синтаксиса константная, не нужно его боятся, даже если он кажется непривычным, он учится один раз и практически никогда не меняется. Более того, хорошей и распространенной практикой в программировании является наличие своего синтаксиса под разные задачи и даже написание своего синтаксиса - DSL, что бы скрыть доменную сложность - семантику. А вот перегрузка операторов - добавление одному и тому же API множества семантик считается плохой практикой, и не зря.
Если синтаксис имеет константную сложность, редко меняется, а даже если меняется - изменение это максимально очевидно (видно глазами), то с семантикой все намного сложнее. Помимо того что в разные моменты жизни программы и разных контекстах выполнениия кода семантика может быть разной (this в обычной функции доступен или не доступен в зависимости от того как вызывается функция и была ли она прибинжена), изменение семантики намного проще реализовать и намного сложнее заметить - это все что нужно для непредсказуемого поведения долгоживущей системы :)
Чем реже меняется семантика - тем лучше. А что бы реже приходилось менять семантику, нужно изначально правильно ее выбрать. Слишком простая семантика заставить создавать кучу нового API, увеличивая количество кода. Слишком сложная семантика будет увеличивать ментальную нагрузку каждой строки кода, и даже если он будет компактный, читать и статически анализировать его может быть дольше и сложнее чем кучу простого кода. Go VS Ruby :)
Так как же найти баланс? Семантика должна хорошо покрывать самые частые случаи использования API, на редкие случаи использования можно иметь дополнительное API. Говоря иначе: синтаксис можно применять по месту и это выразительно (явно), а добавляя семантику мы добавляем ее, скорее всего, вообще везде и для всего проекта, внося лишнюю ментальную нагрузки и там где она не нужна.
Минутка рекламы и пример. В Reatom всегда (во всех функциях) приходится первым аргументом таскать
ctx - это бойлерплейт по синтаксису и даже оверхед по семантике обычного JS (есть же this!), но если написать много кода, то будет видно что ctx идеально вписывается в те задачи, которые разработчик хочет решать такой библиотекой. По количеству символов нагрузка не большая, иногда даже отрицательная по сравнению с другими библиотеками, т.к. ctx можно расширять дополнительными свойствами. А по смыслу такое апи позволяет вообще не задумываться о сложности тестирования, ssr, отмене цепочки асинхронных запросов. Когда доступ к таким вещам упрощается - они становятся нормой, улучшая общий DX разработчика и конечный UX пользователя.