Про GraphQL не чокаясь

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

Суть существования любого API – это предоставление обязательства, контракта для обеспечении связи двух или более программ. Фронтенд с бекендом или бекенд с пользовательскими скриптами о которых сами авторы API ничего знать не могут, или бекенд вашей компании с бекендом другой компании и т.д. Суть проста – предоставить обязательства и надлежаще их выполнять.

С каждым годом кол-во задач для разработки, потребностей у бизнеса и скорость внесения этих изменений в продукты растет, продукты тоже растут и очевидно скрещивать сервисы, клиенты и вообще поддерживать контракт и обязательства становится сложно, а порой невозможно. И причина этому тоже проста – у всех свое понимание, что такое хороший API. Соберите в круг 100 разработчиков ничем не связанных по рабочему опыту и у каждого будет свой ответ. Да, пересечения в ответах конечно будут, но и различий будет не одно.

С моей точки зрения есть отличный заход на попытку натянуть Филдинговскую диссертацию по архитектуре сетевого программного обеспечения на проблему написания API, которая выродилась в секту приверженцев REST "стандарта". Ежели вы почитаете сам первоисточник ( https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm ), то найдете там ничего кроме абстрактных общих рекомендаций. И строиться они будут вокруг того, что строить мы в будущем будем сложные разнесенные децентрализованные сетевые системы поверх интернета и разные сетевые устройства должны по ходу обработки ваших запросов понимать их легко и однозначно. Пережив ряд споров, дискуссий и религиозных разборок сформировались некоторые рекомендации, которые назвались в сообществе RESTfull API. Но вот не задача – писать такие апишки оказывается непросто. Как мы знаем в программировании есть несколько фундаментальных проблем и одна из них это нейминг переменных. Ну вот у разработчиков с неймингом точек входа вообще беда оказалась. А там еще и поверх HTTP спецификации всё натянули и совсем путаница наступила с глаголами и идемпотенцией. Ну да не про рест я пост замыслил. А про графкуэль.

Вернемся к вопросу о хорошем API. Мое имхо (к счастью я не одинок в этом) следующее:

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

Все остальное в целом вторично.

Определив границы качества для себя, я могу сформулировать почему для меня GraphQL мерт по умолчанию:

• Он не семантичен HTTP протоколу (используем только GET & POST)
• Он не понятен промежуточным сетевым устройствам по умолчанию
• Он требует наличие спецификации для понимания его работы
• Данные возвращаемые методом не явны с точки зрения анализа запроса (структура данных, которую мы запрашиваем передается в body через POST), а значит без прямого вмешательства в код сервера обеспечить наложенную защиту или аналитику – не возможно. Ну либо нужно детерменировать запросы, что требует специфического сетевого ПО.

С моей точки зрения попытка мордошариков изобрести некий стандарт для RPC вызовов вышла из под контроля и захватила умы впечатлительных разработчиков. Хорошим API их решение, для меня, стать не может по причинам выше. А в довесок я кажется вижу в его применении с самого начала лень при проектировании архитектуры и протоколов взаимодействия. Кто-то скажет наоборот – это срезание костов! Но я с удовольствием послушаю обоснование выбора решения и почеленжу его. Дьявол всегда кроется в деталях и если натягивать сову на глобус осознанно и с чувством, то польза вероятно от GraphQL может где-то и есть, но я еще не видел в практике ни одного реального сервиса, которому без graphql было бы не обойтись.

А вообще есть крутая книжка Сергея Константинова на тему написания хороших API. Вот уж кто лучше всех сможет научить писать хороший API. https://github.com/twirl/The-API-Book