Comments 67
Soap, вы забыли про soap!
Из своей практики работы со сторонними API:
— сообщения об ошибках в нескольких разных форматах — plaintext, строка в json и массив в json. А в документации чёрным по белому формат описан и он один. Чтобы было совсем не скучно — у сообщения об ошибке нет машиночитаемого кода, только описание — которое для некоторых ошибок может возвращаться на разных языках.
— разные размерности одних и тех же данных. Здесь amount — сумма в валюте клиента, а тут (той же самой сущности рекламного объявления!) amount — всегда в центах USD. О, или ещё лучше: если у клиента валюта «рубли» — то сумма в рублях, если USD — то сумма передаётся… — в центах! Для красоты саму валюту клиента через API не узнать никак.
— в документации в принципе отсутствуют допустимые значения для строк-перечислений, при том как для параметров так и для возвращаемых значений. status => string. Ура! Пишем логирование всех приходящих статусов и разбираемся что есть что по ходу пьесы, т.к. список возможных получить так и не смогли.
— запрос к сервису через API скидывает авторизацию пользователя, с ключом которого запрос выполнили — было крайне нескучно постоянно авторизовываться.
— неожиданные ограничения API — например, у пользователя есть логин и email, в API надо передать email. И вдруг получаем от части пользователей багрепорт, где выясняется что по email только некоторых пользователей авторизовать нельзя. А по логину — нет возможности в API.
— ошибиться в документации с написанием имени параметра. Ну то есть написать checkOutDate вместо реально используемого check_out_date
— в ответе на ошибочный запрос с полусотней параметров сказать «some error occured» без указания, а что именно не так или хотя бы в каком параметре
— сообщения об ошибках в нескольких разных форматах — plaintext, строка в json и массив в json. А в документации чёрным по белому формат описан и он один. Чтобы было совсем не скучно — у сообщения об ошибке нет машиночитаемого кода, только описание — которое для некоторых ошибок может возвращаться на разных языках.
— разные размерности одних и тех же данных. Здесь amount — сумма в валюте клиента, а тут (той же самой сущности рекламного объявления!) amount — всегда в центах USD. О, или ещё лучше: если у клиента валюта «рубли» — то сумма в рублях, если USD — то сумма передаётся… — в центах! Для красоты саму валюту клиента через API не узнать никак.
— в документации в принципе отсутствуют допустимые значения для строк-перечислений, при том как для параметров так и для возвращаемых значений. status => string. Ура! Пишем логирование всех приходящих статусов и разбираемся что есть что по ходу пьесы, т.к. список возможных получить так и не смогли.
— запрос к сервису через API скидывает авторизацию пользователя, с ключом которого запрос выполнили — было крайне нескучно постоянно авторизовываться.
— неожиданные ограничения API — например, у пользователя есть логин и email, в API надо передать email. И вдруг получаем от части пользователей багрепорт, где выясняется что по email только некоторых пользователей авторизовать нельзя. А по логину — нет возможности в API.
— ошибиться в документации с написанием имени параметра. Ну то есть написать checkOutDate вместо реально используемого check_out_date
— в ответе на ошибочный запрос с полусотней параметров сказать «some error occured» без указания, а что именно не так или хотя бы в каком параметре
- Обновляй API как можно чаще: беззастенчиво удаляй лишние запросы, но добавляй новые (обязательные!) параметры в уже существующие. Уведомлять пользователей нет необходимости — сами увидят, когда все сломается.
- Если ты так щедр, что предоставляешь тестовый сервис, то пусть он будет отставать от боевого. И работает раз в неделю. Хотя нет, работать ему необязательно.
Забудь про версионирование API. Пускай каждую неделю/месяц разработчики сами подстраиваются и переписывают приложение под десятки breaking changes. Зато у них всегда будут твои новые фичи.
Если необязательный параметр решили сделать обязательным, или ввести для него ограничения — для этого тоже что ли версию API менять?
Не уверен, что компетентен ответить на этот вопрос. Моя боль с клиентской стороны состояла в постоянном изменении структуры запроса/ответа, их полей и типов.
Обычно принято мажорную версию менять при любом breaking change. Ибо для клиента это может стать сюрпризом.
Если бы обязательный сделали необязательным — ОК, обратная совместимость поддерживается.
Если бы обязательный сделали необязательным — ОК, обратная совместимость поддерживается.
Тот случай, когда стыдно признаться
про меня на хабре написали
В ответ на запрос отправлять «запрос обработан», а чтобы получить ответ, надо вызывать отдельный метод «дай_ответ», который будет отправлять ответ на какой-нибудь запрос (маппить запрос-ответ будет клиент API по айдишникам).
Вообще, если ваш запрос был заявкой на длительную операцию по обработке, то это вполне разумный организации асинхронных запросов.
вот это уже стандарт — есть HTTP код 202 accepted, который означает, что запрос принят на обработку
и в лучших сценариях в ответе есть url, или иной способ получить статус действия
и в лучших сценариях в ответе есть url, или иной способ получить статус действия
Если у автора фамилия не «Остер», то он явно его родственник
checkInDate/checkOutDate
Смотрел на эту конструкцию, как среда на пятницу.
Очень похоже на описание внутренней структуры SAP'a.
Если нужно вернуть код ответа, отличный от дефолтного, посылайте
{ code: 403, message: "У вас нет прав" }
с HTTP кодом 200
Вот буквально в час ночи от сегодня в одном API сменились лимиты и вот хоть стой хоть падай, пока тех поддержка отвечала, выяснил с внезапно изменившейся документацией без версий и логов, что лимиты так прилично зарезали. Очень классный кипеш был с утра в паре интернет магазинов. И это я уже научен горьким опытом от греха хранить полный ответ сервера апи.
Пфф. Все гораздо проще. Возьмем API ВКонтакте для примера:
1. Введите маленький лимит на число запросов для замедления работы всех приложений.
2. Возвращайте каптчу на запросы от серверного API и предлагайте показать ее пользователям, которые оффлайн.
3. Когда лень показывать каптчу, просто возвращайте ошибку «Flood control», т.к. запросы к API посылаются, внимание, слишком однотипные (ведь в API нужно использовать как минимум 99% из доступных методов, хотя они вам не нужны).
P.S. Извините, накипело.
1. Введите маленький лимит на число запросов для замедления работы всех приложений.
2. Возвращайте каптчу на запросы от серверного API и предлагайте показать ее пользователям, которые оффлайн.
3. Когда лень показывать каптчу, просто возвращайте ошибку «Flood control», т.к. запросы к API посылаются, внимание, слишком однотипные (ведь в API нужно использовать как минимум 99% из доступных методов, хотя они вам не нужны).
P.S. Извините, накипело.
example.com/myService?d=11.12.05&d=12.12.05&d=13.12.05&colors=green;yellow
На сервер передастся d=13.12.05
example.com/myService?d[1]=11.12.05&d[2]=12.12.05&d[3]=13.12.05&colors=green;yellow
— так понятнее будет
Зависит от обработчика, вот обсуждение на SO.
Отнюдь, нужно использовать первый вариант, а потом вручную парсить строку запроса на сервере, даже если бэкенд написан на PHP. Пусть программисты, которым поддерживать этот код после вас, поломают головы :-)
Кроме шуток, встречал такое разок.
Черт, пара пунктов исполнена, но это из-за легаси и обратной совместимости, честно!
бесят эти ендпоинты и гэт-параметры,
лучше эндпоинт писать в хедер
дада… именно в верхнем регистре, это подчеркнет властность над глупыми машинами!
и гэт параметры:
так будет урл красивый! И данные спрятаны под капотом.
А чтобы совсем не скучно было:
1. эндпоинт хешируем: md5(base64(..))
2. бекэнд смотрит таблицу эндпоинтов в md5(base64(..))
3. если мд5-баса64 не найдет — статус писать 200-ОК, респонс писать {BAD} — и так чтобы было похоже на ясон, но не получилось прочитать как ясон, пусть знают как неправильные ендпоинты отправлять!!!
4. обязательно нужно обернуть хедер гетов в какойнибуть base64, можно даже несколько раз, или свою функцию написать в свободное время
ох, самое важное — отовсюду в коде стирать свои копирайты, емейлы, телефоны!…
А еще лучше — вписать кругом контактные данные одноклассника, который у тебя булочки отбирал, будет знать!!!
лучше эндпоинт писать в хедер
MY-HEADER-ENDPOINT="/users"
дада… именно в верхнем регистре, это подчеркнет властность над глупыми машинами!
и гэт параметры:
MY-HEADER-GET=«key1=value1<ITS-MY-SEPARATOR>key2=value2»
так будет урл красивый! И данные спрятаны под капотом.
А чтобы совсем не скучно было:
1. эндпоинт хешируем: md5(base64(..))
2. бекэнд смотрит таблицу эндпоинтов в md5(base64(..))
3. если мд5-баса64 не найдет — статус писать 200-ОК, респонс писать {BAD} — и так чтобы было похоже на ясон, но не получилось прочитать как ясон, пусть знают как неправильные ендпоинты отправлять!!!
4. обязательно нужно обернуть хедер гетов в какойнибуть base64, можно даже несколько раз, или свою функцию написать в свободное время
ох, самое важное — отовсюду в коде стирать свои копирайты, емейлы, телефоны!…
А еще лучше — вписать кругом контактные данные одноклассника, который у тебя булочки отбирал, будет знать!!!
В POST-запрос всегда одну половину параметров передавай в body запроса и другую как в query-параметры в URL.
Единицы измерения: очень хорошо, когда одно и то же значение должно в разных местах задаваться разными единицами измерения. Или чтобы прочитать можно было только в одной единице, а записывать — только в другой.
Требуйте обязательного заполнения как можно большего количества полей. Особенно, если бизнес-процесс предполагает, что некоторые данные иногда сразу получить невозможно.
Требуйте наличия поля «дата документа», которое должно совпадать с текущей датой. Особенно, если данные поступают круглосуточно. Особенно, если принимаются данные из другого часового пояса.
Ещё — очень хорошо требовать определённый порядок полей в XML.
Требуйте обязательного заполнения как можно большего количества полей. Особенно, если бизнес-процесс предполагает, что некоторые данные иногда сразу получить невозможно.
Требуйте наличия поля «дата документа», которое должно совпадать с текущей датой. Особенно, если данные поступают круглосуточно. Особенно, если принимаются данные из другого часового пояса.
Ещё — очень хорошо требовать определённый порядок полей в XML.
А вообще, какой-такой API, давайте мы будем присылать экселевские файлики по почте. Или на FTP.
Хе, на почту. На 1.44 дискетку в дочерном офисе во Владивостоке с паспортом и бумажным заявлением с мокрой печатью. Если ексельник 100-метровый — архивируется и каждый архив кидается на дискету. Для самой смакотки вместо 43-й части можно повторно кинуть 42-у.
Кстати с экселем, отсылаемым на почту вполне себе работоспособный вариант — это один из возможных способов для оператора связи отчитаться перед министерством связи по различным статистическим показателям.
Надо было скомбинировать данные стороннего api и сервиса для создания api для нужд сайта. Сделал франкенштейна из этих данных и это угнетает. Как было бы сделать правильно?
Зачем нужны коды ошибок?
Только подробное описание, которое, может быть, разработчик поймет
Только подробное описание, которое, может быть, разработчик поймет
{
errorMessage: "DB: uniqueConstraint error for asdf@email.ru"
}
ISO 8601 — это еще тот стандарт для любителей веселухи.
Из практики, почти всегда можно найти вариант, который будет полностью соответствовать стандарту, но не поддерживаться или неправильно интерпретироваться конкретной библиотекой.
Так что, да, указывайте просто ISO 8601, вместо например RFC 3339. Тестерам это реально доставит :-).
Из практики, почти всегда можно найти вариант, который будет полностью соответствовать стандарту, но не поддерживаться или неправильно интерпретироваться конкретной библиотекой.
Так что, да, указывайте просто ISO 8601, вместо например RFC 3339. Тестерам это реально доставит :-).
Это всё конечно хорошо, но вот в пункте 8 у меня появился вопрос: где же хранить сами флаги, если не в документации и в коде, использующем их?
У меня вот иногда под флаги отдельный файл сделан, чтобы в нём хранить их… Чяднт?
У меня вот иногда под флаги отдельный файл сделан, чтобы в нём хранить их… Чяднт?
Да, тут пункты, по-моему, несоизмеримы.
Часть пунктов — реально жесть, но некоторые — скорее отображают неприятие автором некоторых вещей (которые, если их правильно готовить, в принципе неплохи (а если готовить неправильно, так что угодно сломать можно)).
Хотя это юмор, так что требовать точности — вряд ли уместно.
Часть пунктов — реально жесть, но некоторые — скорее отображают неприятие автором некоторых вещей (которые, если их правильно готовить, в принципе неплохи (а если готовить неправильно, так что угодно сломать можно)).
Хотя это юмор, так что требовать точности — вряд ли уместно.
Я лично таких API не писал, но, по-моему, некоторые из пунктов (или, точнее, некоторые из частей некоторых пунктов) — например: 5 («передавай вложенные структуры как список плоских»), 7 («замени True/False на 1/0» — только тогда, конечно, точные названия выбирать надо), 8 («используй битовые флаги»), 9 («[уточните, нет в продаже, нет в наличии, количество товара в наличии]» — если эти значения действительно взаимоисключаемые по логике приложения), 10 («обязательный параметр, у которого может быть только одно значение» — например, номер версии) — вполне приемлемые в определённых сферах или, по крайней мере, пусть и плохи, но на порядок лучше других (то есть степень вреда разных пунктов несоизмерима; например, если нет вменяемого отчёта об ошибке, отличимого от успешного ответа — это бардак; а если возвращается битовая маска, но она хорошо задокументирована, то это ок).
Из моего, недавнего:
1) в разных методах апи возвращайте разные объекты(в документации сделайте копипаст)
2) внутри апи сделайте разные методы, которые возвращают объекты и счётчик по ним, а потом исправьте ошибки только в одном из этих методов
1) в разных методах апи возвращайте разные объекты(в документации сделайте копипаст)
2) внутри апи сделайте разные методы, которые возвращают объекты и счётчик по ним, а потом исправьте ошибки только в одном из этих методов
По 7 пункту я сразу вспомнил фьюзы у микроконтроллеров AVR. Где 0 — это установлен. И можно было бы привыкнуть, но некоторые программы для прошивки инвертируют их. Что запутывает окончательно, особенно когда используешь несколько таких программ.
Документация? Конечно, должна быть! Такая, ммм, по всем правилам из поста. Без примером и ограничений. И при любой проблеме мы будем отправлять пользователя перечитывать ее. Не зря ж писали.
Sign up to leave a comment.
Нескучный API