Комментарии 25
Функциональные тесты с помощью dredd
Как вы решаете вопросы установки прекондишенов для тестов? Мы пробовали — по итогу я считаю что это бесполезная вещь, с большего потому что долго и потому что прекондишены выставлять сложно. Мы из apiblueprint генерим jsonschema и тестируем точки выхода на предмет совпадения схемы. В итоге можно получить полное покрытие всей API.
Ну или можно заюзать graphql где схема жестко задекларирована и ее проще проверять.
Фактически, использование именно сервиса Apiary (и формата apiblueprint, как следствие) обусловлено необходимостью иметь актуальную документацию по API с минимальной тратой ресурсов на ее поддержание.
С учетом того, что код покрыт модульными тестами (прекондишены мы тестируем именно там), достаточно видеть, что API возвращает что-то более-менее похожее на правду.
Вы храните документацию вместе с кодом?
А по коммиту в репозиторий файлы склеиваются в один и публикуются на apiary
А редактируете API через что?
блупринт это в целом просто маркдаун, я за 2 года использования не заметил необходимости использовать что-то еще. Можно просто линтер фоном запускать.
А вообще рекомендую еще посмотреть в сторону raml1.0.
Предлагаю ввести термин "default API" по аналогии с "default city". Чтобы сразу было ясно: если в заголовке упомянуто API — это исключительно для веб-приложений, всяким шудрам, пишущим не для веба, можно не заглядывать.
Да не обращайте внимания, это так, шутливое ворчание. Даже я догадался, что речь про веб — хотя в ленте на m.habrahabr.ru ничто на это не указывает (но именно потому что в любой другой области автор указал бы, о каком API идёт речь, а в вашей области разработчики зачастую забывают, что существует остальной мир).
стоит добавить RESTful API в название?
не стоит, ибо restful api не бывает. Можно назвать это http api и это будет честно.
HTTP RESTish API :)
вся проблема в том что rest это архитектурный стиль, используемый web-ом, ключевое тут — гипертекст. И если ваши мобилки не умеют строить UI используя гипертекст — то взаимодействие клиент-серверное не может быть описано как rest. Вот и все.
именно в этом «архитектурном стиле»,
гипертекст в нем, в большинстве своем не используется
Если там нет гипертекста, нет HATEOAS, значит это нельзя описать "этим" архитектурным стилем. HATEOAS является одной из основных вещей в WEB (и в REST, поскольку оно именно WEB и описывает) которая является эдакой киллер фичей, позволяющей бесконечнйы скейл в купе с URI.
Хорошая новость — нам это и не нужно. Потому не надо подменять понятие "rest" до "http"… слишком много хороших идей таким образом размыло до того что все потеряло всякий смысл. И нет смысла пытаться впихнуть гипертекст в апишки для мобилок и т.д.
Гипертекст, формально говоря, — это текст со ссылками на другие гипертексты (википедия).
Гипермедиа, отвечающая за «H» в HATEOAS, в свою очередь, в любом REST сервисе используется практически всегда, так как в нее входят помимо размеченного текста еще и медийные ресурсы (фото, аудио, видео)
REST никоим образом не завязан на гипертексте, мне гораздо чаще встречались реализации с данными в формате JSON.
вы читали первоисточник? REST это архитектурный стиль. Что значит "архитектурный стиль" — это совокупность ограничений накладываемых на систему. Какие у нас есть ограничения:
- клиент-сервер
- stateless
- cacheable (прямое следствие предыдущего)
- uniform interface
- Identification of resources
- manipulation of resources through representations
- Self-descriptive messages
- hypermedia as the engine of application state
- layered system
- code-on-demand (опционально)
Вот если у вас всего этого нет — у вас не REST. На сегодняшний день единственное что подходит под описание REST — это сам Web. Что не удивительно ибо вся эта замута с REST является лишь описанием почему Web сделан так как сделан.
Гипермедиа, отвечающая за «H» в HATEOAS, в свою очередь, в любом REST сервисе используется практически всегда, так как в нее входят помимо размеченного текста еще и медийные ресурсы (фото, аудио, видео)
вы можете добавить ссылочки в ваш json но клиент от этого не будет сам добавлять что-то на UI. Реальность такова что на клиенте хардкодится что отображать и в каком контроле. Если вы прислали картинку — ее кинут в конкретный UI контрол. В случае с JS это будет либо элемент img либо video. В любом случае конкретный вариант будет задан явно.
Более того, HATEOAS это декларация переходов между различными состояниями, которое декларируется элементами гипермедиа (теги a и form в html). Эти элементы скрывают действие которые надо совершить клиенту. И за счет того что у нас сервер отвечает за описание переходов мы можем скейлиться не меняя клиенты. С мобилками увы так не выйдет ибо это будет равносильно реализации браузера что точно никому не нужно. Намного проще взять какой graphql и фигачить json-ки не заморачиваясь.
Вероятно, имелось в виду, что на практике их не существуют. Никто в здравом уме не делает полноценные REST API — овчинка выделки не стоит.
В целом VolCh правильно мысль раскрыл. Оно никому не нужно. А то что вам нужно — просто API использующее HTTP как транспорт. Транспорт где на уровне спецификации заложены базовые фреймворки для кэширования, авторизации, который неплохо расширяем и очень хорошо распространен.
Использовать чистый HTTP как прикладной протокол не эффективно. Именно поэтому у вас есть документация в apiblueprint с примерами поведения вашей надстройки над HTTP. И по сути мы от REST используем только те пункты которые относятся к HTTP.
Потому я бы просто предложил не использовать этот термин. Вообще. HTTP API вполне себе хорошо описывает суть того что нам нужно. Мы все еще можем брать идеи "ссылок" на связанные ресурсы, в угоду information hiding, но это далеко от гипертекста. Более того, лично я был удивлен что андройдщикам это "неудобно".
может именоваться REST API?
В идеале даже если мы решимся на это и реализуем подобное, тут будет конфликт терминологии. API про контракты, REST про переход из одного состояния в другое, и гипертекст как способ декларировать эти переходы. То есть мы не можем выделить контракт когда говорим о REST. У вас может быть спецификация описывающая как клиент должен реагировать на отдельные элементы гипермедиа, но это не контракт.
Правила хорошего тона для API