Про api

[stdray]

Чем меньше обещаний, тем проще их соблюдать. Можно пообещать json, а дальше пусть опирается на значения по умолчанию https://t.co/C0nEYyDFp6

— Разработчик бэкенда (@backendsecret) 8 Март 2016

Регулярно всплывает тема запиливания хорошего годного интерфейса к ентим нашим оперденям. И все глубокомысленно отвечают, что вопрос давно решен, и REST API - наше все. А потом все столь же глубокомысленно кивают, мол всё так, всё так. Хотя по факту имеем набор нечетких рекомендаций вида:
- http в качестве транспорта
- json в качестве данных
- url в качестве идентификаторов сущностей
- http verbs в качестве действий.

Это ответ на вопрос? Я считаю, что это лел. Это как в известной песне: "Думайте сами, решайте сами". Если у вас нет обещаний, то и некому их нарушать.


REST - это такая разновидность ленивого программирования.

У нас есть веб-сервис, который отдает вам очень ценные данные в json. Вот! Надо будет - разберетесь. Что? Не выходит? Ну давайте сгенерируем вам великолепные странички, где продемонстрируем:
- шаблоны url с качественными примерами подстановочных значений
- примеры json-ответов с объективно достаточным набором заполненных полей

Ой бл. Вы опять тупите? Какие-то проблемы - не проходят post и put запросы? Ну это же очевидно, как ее решить - у вас же ОБЯЗАТЕЛЬНЫЕ поля не заполнены))) Ладно, ладно, мы добавим это в документацию нашего API.

В каком смысле у ваc ничего не работает c 401 ошибкой? Давайте конкретней. Даже get ничего не отдает? Хмм. А понятно, у вас же не заполнен заголовок с вашим АА-ключом. Нет, теперь Authorization header мы не смотрим. Сейчас мы работаем иначе, мы вам вышлем письмо. Почему нет в документации? Странный вопрос)

У вас опять ничего не работает? Странно. Хорошо, пришлите мне примеры ваших запросов, я погляжу. Ахахаха. Вы знаете, формально это другое API, его разрабатывает другая команда. Я, честно говоря, не в курсе как им надо передавать заголовок авторизации. Ну и принцип формирования url у них другой, я не знаю, почему они так сделали. Давайте, вы лучше напишите вот на этот email, возможно, вас кто-то и проконсультирует.

Я утрирую, но самую малость. Переложили с больной головы на здоровую и радуемся. По сути, весь ентот REST преследует одну цель - дать возможность работать с минимальной инфраструктурой. То есть http и json библиотек должно быть абсолютно достаточно, всё остальное раскурит и напишет разработчик. Если мы что-то добавим, изменим - всё это на совести разработчика клиента к нашей опердени.

Все эти надстройки над json, которые должны давать какую-никакую схему, все эти protobuf или apache thrift - сложные маргинальные технологии. SOAP - это энторпрайзно сложный бойлерплейт, у нас нет времени ебаться с ним. Кроме всего, XML - это слишком большой оверхед на передаче данных.

Я согласен с тем, что SOAP сложно, хотя проблемы обычно начинаются в области ws-расширений, а сам по себе протокол для лелов. Вот тебе схемы, вот тебе набор методов - вперед. Трифт примерно такой же. Они похожи на решения проблем, пусть и со своими недостатками. Раз есть решение, есть и недостатки - так всегда бывает.

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

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

Вот собственно и всё. Понятно, что отношение к этому всему сильно зависит от выбранного языка программирования, но мое вот такое.