Правила хорошего тона для API
Комментарии (14)
Fesor
21 июля 2017 в 19:03 (комментарий был изменён)
0↑
↓
Функциональные тесты с помощью dredd
Как вы решаете вопросы установки прекондишенов для тестов? Мы пробовали — по итогу я считаю что это бесполезная вещь, с большего потому что долго и потому что прекондишены выставлять сложно. Мы из apiblueprint генерим jsonschema и тестируем точки выхода на предмет совпадения схемы. В итоге можно получить полное покрытие всей API.
Ну или можно заюзать graphql где схема жестко задекларирована и ее проще проверять.
ValeriaVG
21 июля 2017 в 19:30
0↑
↓
В общем случае, мы описываем пары Request/Response для ситуаций, где меняется JSON-схема: например, для успешного ответа и ответов с ошибками.Фактически, использование именно сервиса Apiary (и формата apiblueprint, как следствие) обусловлено необходимостью иметь актуальную документацию по API с минимальной тратой ресурсов на ее поддержание.
С учетом того, что код покрыт модульными тестами (прекондишены мы тестируем именно там), достаточно видеть, что API возвращает что-то более-менее похожее на правду.
-
Fesor
22 июля 2017 в 10:18 (комментарий был изменён)
+1↑
↓
С той же мыслью используем и в целом примерно так же. Просто сейчас хотим уйти от дрэда ибо неудобно если цель просто схему проверить.
Но на документацию это решение не сказывается.
Mehdzor
21 июля 2017 в 19:23
0↑
↓
Вы храните документацию вместе с кодом?
-
ValeriaVG
21 июля 2017 в 19:32
0↑
↓
Да, документация разбита на несколько файлов, которые можно тестировать отдельно или вместе.
А по коммиту в репозиторий файлы склеиваются в один и публикуются на apiary-
Mehdzor
21 июля 2017 в 19:39
0↑
↓
А редактируете API через что?
-
ValeriaVG
21 июля 2017 в 19:57
0↑
↓
Через текстовый редактор, у Apiary есть web-редактор, но для объемных файлов он не очень удобен-
Mehdzor
21 июля 2017 в 20:11
+1↑
↓
Никакими превью не пользуетесь? В Apiary больше всего бесило это, что для нормального редактирования приходится на уши вставать. И сам стандарт пока сырой аж капец как.
-
ValeriaVG
21 июля 2017 в 21:51 (комментарий был изменён)
0↑
↓
Нет, JSON — синтаксис разве что.Есть api-blueprint-preview для Atom’а, но лично не тестировала.
-
Fesor
22 июля 2017 в 10:20
+1↑
↓
блупринт это в целом просто маркдаун, я за 2 года использования не заметил необходимости использовать что-то еще. Можно просто линтер фоном запускать.
А вообще рекомендую еще посмотреть в сторону raml1.0.
-
ValeriaVG
22 июля 2017 в 12:39 (комментарий был изменён)
0↑
↓
Спасибо, на первый взляд — хороший вариант, обязательно выделю время на изучение.
22 июля 2017 в 00:27
–1↑
↓
Предлагаю ввести термин «default API» по аналогии с «default city». Чтобы сразу было ясно: если в заголовке упомянуто API — это исключительно для веб-приложений, всяким шудрам, пишущим не для веба, можно не заглядывать.
-
ValeriaVG
22 июля 2017 в 12:37
+2↑
↓
Признаюсь, мне и в голову не приходило что кто-то может подумать, что статья про API Arduino, к примеру, да и в анонсе статьи вроде бы недвусмысленно обозначена тематика. Возможно стоит добавить RESTful API в название?22 июля 2017 в 17:53 (комментарий был изменён)
0↑
↓
Да не обращайте внимания, это так, шутливое ворчание. Даже я догадался, что речь про веб — хотя в ленте на m.habrahabr.ru ничто на это не указывает (но именно потому что в любой другой области автор указал бы, о каком API идёт речь, а в вашей области разработчики зачастую забывают, что существует остальной мир).
