Комментарии 22
Привет :)
Спасибо за трепетную душешипательную историю, занятно написано :)
Смотрю вот на Суть.
Интересно, что под капотом?
Оно как-то само собирается и т.п. и т.д., или есть ещё к этому редактор?
М.б. чем-то пользуетесь/планируете и т.п., например:
Swagger, apiary или apiblueprint?
Спасибо за трепетную душешипательную историю, занятно написано :)
Смотрю вот на Суть.
Интересно, что под капотом?
Оно как-то само собирается и т.п. и т.д., или есть ещё к этому редактор?
М.б. чем-то пользуетесь/планируете и т.п., например:
Swagger, apiary или apiblueprint?
Интересно, что под капотом?
Оно как-то само собирается и т.п. и т.д., или есть ещё к этому редактор?
Под капотом PHP в связке с MySQL.
Как и в случае с примером про полуавтоматическое созданием приложения, я заленился и сделал себе инструменты, чтобы «просто выбрал, заполнил – и в продакшен». Есть внутренняя админка на меня одного, и в ней даже не нужно настраивать некий краудин, чтобы делать транслэйторам переводы.
Т.е. весь проект документации – полностью самописная вещь, которой удобно пользоваться лично мне. Но как знать, может, в будущем попробую сделать из этого отдельный проект.
М.б. чем-то пользуетесь/планируете и т.п., например:
Swagger, apiary или apiblueprint?
Да, мы знали о них, но тут я решил прокачать свой скилл, а не использовать готовое. Сейчас система работает правильно, ошибок не наблюдается. Теоретически, ее можно развивать и использовать и как отдельный продукт, и для других документаций внутри нашей компании. Если будем где-то еще использовать, обязательно сравню и сделаю обзор
Распространения php модуля для API по средствам zip? Думаю лучше залить его на гитхаб, и добавить на packagist?
Также не увидел тестов, и неймспейсов, да и вообще будем говорить на на чистоту, код на пхп явно попахивает.
Да там еще и global (((
Также не увидел тестов, и неймспейсов, да и вообще будем говорить на на чистоту, код на пхп явно попахивает.
Да там еще и global (((
Это же ucoz
Максим, в случае с zip мы исходили из того, как будет удобно ядру аудитории. По форуму, по опыту техподдержки выяснили – многим клиентам лучше именно в архиве подать файлы и написать документацию в вебе. Хотя гитхаб – это, конечно, позитивно, хорошо и правильно
То есть вы говорите что ваша аудитория застряла году эдак в 2010 и это нормально?
Заголовок не оправдывает ожиданий.
Думал увидеть какую-то общую статью, где бы говорили про версионность, обратную совместимость и прочие проблемы и тд. А по факту получил рассказал про то, как плохо подошли к этому в вашей компании
Думал увидеть какую-то общую статью, где бы говорили про версионность, обратную совместимость и прочие проблемы и тд. А по факту получил рассказал про то, как плохо подошли к этому в вашей компании
Илья, пока две версии API живут отдельно (у старой есть свои пользователи, их не стали трогать), но если столкнемся с вашими вопросами, обязательно расскажем.
Надеемся, опыт «было-стало» тоже может быть полезен.
Надеемся, опыт «было-стало» тоже может быть полезен.
Да, я тоже не понял что же они поняли?
Коротко: мы поняли, как делать удобнее. А я — как стать лучше:
1) Когда я начал заниматься им, собирал информацию, о чем просили клиенты когда-то: какие-то дополнения, фишки, скриптики. И в процессе создания АПИ я понял, что это все возможно. Нет ограничений, ты свободный художник. Вопрос лишь в ресурсах (ну и борьбе с ленью, конечно).
2) Понял, как интересно общение с клиентами. Это невероятное чувство, когда тебе клиент пишет какую-то задумку, и вместе с ним ты погружаешься в эту идею и помогаешь ему, в том числе с кодом.
3) Ну и пару лет назад не поверил бы, что смогу написать свою систему управления документацией. И это [извините]
1) Когда я начал заниматься им, собирал информацию, о чем просили клиенты когда-то: какие-то дополнения, фишки, скриптики. И в процессе создания АПИ я понял, что это все возможно. Нет ограничений, ты свободный художник. Вопрос лишь в ресурсах (ну и борьбе с ленью, конечно).
2) Понял, как интересно общение с клиентами. Это невероятное чувство, когда тебе клиент пишет какую-то задумку, и вместе с ним ты погружаешься в эту идею и помогаешь ему, в том числе с кодом.
3) Ну и пару лет назад не поверил бы, что смогу написать свою систему управления документацией. И это [извините]
Но оказалось, что наши обычные тестировщики не очень подходили для работы с API — ведь они “заточены” под тестинг веб-страниц. API же — тонкая вещь.
Покрыть API тестами и прогонять их каждый раз чтобы понимать что ничего не сломалось — не подходит? Как по мне — мануальное тестирование для API — это перебор. Или что нужно понимать под тестированием? Закрытая публичная версия?
Например, когда происходило изменение внутри модуля, с которым мы интегрировались, что-то могло отвалиться — но тестировщики сначала этого не замечали (потом мы их научили).
Судя по всему, автоматизированным тестированием занимаются мануальные тестеры. Хм…
«А запрос там вообще не отвалился? Он вообще что-нибудь отдает?» — это случай для автотестов. Но, как я писал в постскриптуме, само по себе апи очень чувствительно относится к любым имениям для веб-версии.
Например, после недавнего обновления мы обнаружили забавный баг: ответ от API приходил и вроде бы все хорошо… но данные для одного поля он выдавал вообще левые. Вопрос – а как быть в таких случаях? Пока лучше ручного теста – не нашли. Заодно ребята-тестировщики обучаются составлению запросов и другим интересным вещам.
Например, после недавнего обновления мы обнаружили забавный баг: ответ от API приходил и вроде бы все хорошо… но данные для одного поля он выдавал вообще левые. Вопрос – а как быть в таких случаях? Пока лучше ручного теста – не нашли. Заодно ребята-тестировщики обучаются составлению запросов и другим интересным вещам.
>>ответ от API приходил и вроде бы все хорошо
Это как понять? Вы считаете код 200 ответом, или я не так Вас понял?
В первую очередь Ваш API должен возвращать данные, написанные в вашей спецификации к нему — она ведь у Вас есть?
Второе, это кольцевое тестирование. Когда за запрос к серверу дублируется запросом в базу а результаты сравниваются, естественно такое тестирование не всегде покроет все случаи, но скажем простые GET/POST/UPDATE/DELETE запросы к данным он проверит идеально.
PS. Я глубоко удивлен Вашем повествованием о тестеровщиках, которые толи не знают, толи не понимают как создать HTTP запрос… боюсь спрашивать о использовании таких инструментах как Jmeter/SoapUI вашими тестеровщиками.
Это как понять? Вы считаете код 200 ответом, или я не так Вас понял?
В первую очередь Ваш API должен возвращать данные, написанные в вашей спецификации к нему — она ведь у Вас есть?
Второе, это кольцевое тестирование. Когда за запрос к серверу дублируется запросом в базу а результаты сравниваются, естественно такое тестирование не всегде покроет все случаи, но скажем простые GET/POST/UPDATE/DELETE запросы к данным он проверит идеально.
PS. Я глубоко удивлен Вашем повествованием о тестеровщиках, которые толи не знают, толи не понимают как создать HTTP запрос… боюсь спрашивать о использовании таких инструментах как Jmeter/SoapUI вашими тестеровщиками.
Нет, речь не про 200 код. Я про то, что если в ответе пришло что-то наподобие success или большой набор полей – понятно, что запрос не отвалился. Вот понять, что «он скорее жив» или наоборот – это уже следующая задача.
Покажу на примере, про который говорил:
Поступало:
Должно было:
Думаю, ваш вариант по поводу кольцевого тестирования – да, вероятно, помог бы в этой ситуации. Буду думать, спасибо.
Покажу на примере, про который говорил:
Поступало:
"goods_list":"<table><tr><td>текст</td></tr></table>
Должно было:
"goods_list":{
"1":{
"entry_is_in_discount":1,
"entry_weight":{
"weight":0,
"weight_raw":"0.0000"
},
"entry_stock":{
"stock_total":"0",
"stock":3
},
"entry_brief":"Если вам нужен красивый и запоминающийся UIN, этот товар для Вас.\r Данный товар имеет тип \"Электронный код\". Это означает, что пользователь после оплаты получит код, указанный при создании товара. Один код может быть куплен один раз."
Думаю, ваш вариант по поводу кольцевого тестирования – да, вероятно, помог бы в этой ситуации. Буду думать, спасибо.
В таком случае пишется тест:
1. Первый запрос на добавление / изменение данных
2. Второй запрос на получение данных и проверку корректности данных (вы должны получить те же данные, что и сохраняли, проверить по определенным признакам, иногда прибегая к регулярным выражениям или косвенным признакам — наличии определенной последовательности символов / данных)
Либо если запрос сразу возвращает ответ — проверка полученных в ответе данных.
Или вы пытались описать какую то иную проблему?
1. Первый запрос на добавление / изменение данных
2. Второй запрос на получение данных и проверку корректности данных (вы должны получить те же данные, что и сохраняли, проверить по определенным признакам, иногда прибегая к регулярным выражениям или косвенным признакам — наличии определенной последовательности символов / данных)
Либо если запрос сразу возвращает ответ — проверка полученных в ответе данных.
Или вы пытались описать какую то иную проблему?
Не хочу показаться занудой, но кажется Вы только что сделали то, что нужно было еще вчера.
Про тестеров доставило.
Про тестеров доставило.
может и ошибусь, но странно в современном мире видеть Map (php-array) структуру данных для API
Если у вас строгий запрос — создайте класс, люди будут вам благодарны.
Определите полностью модель поведения и спроектируйте интерфейс.
Создайте реализацию интерфейса на рандомных данных, обвесьте тестами рандомные данные.
Делайте реализацию интерфейса.
На endpoint API вешаете версионность через враппер интерфейса.
Мы на своей команде тестировали.
У нас джуниор нулевой написал приложение (мобильное) как аналог whatsapp в качестве задачи по обучению (изображения + медиаданные) за 2 дня. Сервер пилился по мере написания приложения. (но интерфейс api и рандомные данные были готовы)
Делали аналог rpc
Response: {status:code, error:null, data:{somedataobject}}
В поле data приходят нужные данные.
array в PHP это мощный инструмент, но он дает путь к множеству ошибок и непонимания со стороны разработчиков. Аналог array в Java это будет Map<String, ...>, в других языках это будет более сложный объект.
Если вы следуете понятию Json-Объект, то лучше и создавать классы из которых будут порождаться объекты, на этом этапе у вас мобильный API из коробки будет (java-gson-retrofit). Ну а дальше не долго на какой либо protobuf перейти и транспорт сменить при желании.
Если у вас строгий запрос — создайте класс, люди будут вам благодарны.
Определите полностью модель поведения и спроектируйте интерфейс.
Создайте реализацию интерфейса на рандомных данных, обвесьте тестами рандомные данные.
Делайте реализацию интерфейса.
На endpoint API вешаете версионность через враппер интерфейса.
Мы на своей команде тестировали.
У нас джуниор нулевой написал приложение (мобильное) как аналог whatsapp в качестве задачи по обучению (изображения + медиаданные) за 2 дня. Сервер пилился по мере написания приложения. (но интерфейс api и рандомные данные были готовы)
Делали аналог rpc
Response: {status:code, error:null, data:{somedataobject}}
В поле data приходят нужные данные.
array в PHP это мощный инструмент, но он дает путь к множеству ошибок и непонимания со стороны разработчиков. Аналог array в Java это будет Map<String, ...>, в других языках это будет более сложный объект.
Если вы следуете понятию Json-Объект, то лучше и создавать классы из которых будут порождаться объекты, на этом этапе у вас мобильный API из коробки будет (java-gson-retrofit). Ну а дальше не долго на какой либо protobuf перейти и транспорт сменить при желании.
Зарегистрируйтесь на Хабре , чтобы оставить комментарий
5 стадий API: что мы поняли, написав две версии