korchasa/api_of_dream.md

## api_of_dream.md

      
    Raw
  

              api_of_dream.md
            
          
    Web API моей мечты


Смешная цитата


Его разработчики любят своих клиентов


API для программиста так же важен, как UI для пользователя
Программисты - «клиенты» API. Простота интеграции -> больше клиентов.
Клиенты важнее религии (rest и много запросов)
Код в API заменяет код у всех клиентов


Его легко попробовать


Я могу найти документацию. Быстро.
Я могу его оценить за 15 минут
Даже быстрее (отдельный документ с парой примеров на самые популярные кейсы)
У него есть песочница или она и не требуется (пример с ebay и 2 дня)
У него есть готовое SDK под разные языки (в стиле языка, под которое он написан)


У него хороший протокол


Распространенное by default
Человекочитаемое by default
Не надо забивать гвозди помидором (пример с rpc для справочников)
Не надо религии (не все умеют PUT/DELETE, не все умеют обрабатывать не 200)
Не надо велосипедов
В ответах будет мета-информация (ошибки, пейджинация, инфомрация о лимитах)


У него понятные вызовы (endpoints)


В терминах предметной области, а не assets/items/objects
С namespace’ами
С shortcut'ами для CRUD и глаголами для действий
В едином стиле
Желательно, с одним очевидным способ сделать что-то (пример fql)


Его легко отлаживать


Большая часть ошибок: забыли поле, поле в неправильном формате
SDK с проверками убирает большинство проблем, но порождает необновляемый внешний контракт
сurl (да хоть httpie) в документации (запасной канал для сравнения, средство передачи проблемных каналов)
Человеческие сообщения об ошибках
Ссылки на документацию при ошибках


Оно не усложняет мою систему


Атомарное лучше многоступенчатого
Stateless лучше statefull
Оно сможет сделать мне push вместо пуллинга с моей стороны, если я этого хочу
Оно позволит мне работать без изменения моей модели данных
Оно не усложняет мой код (например, правила по формированию id транзакции)


Оно управляемое


У него будет достаточная для меня вложенность ("объект + дети" или "объект + дети без подробностей")
Я смогу брать не объекты целиком, а только их части
Управление размером страниц в списках
Я смогу запрашивать несколько объектов (по id) //TODO


Оно работает


Разработчики дают попробовать новое, если я этого сам хочу
Разработчики стараются не ломать обратную совместимость
Если сломать совместимость необходимо, то меня предупредят (письма, варнинги в вызовах)