Может ли быть API не как API?

Привет.
У меня вопрос в плане подхода, который использует мой тимлид и от которого меня аж трясет.
А теперь уже и сомнение возникло, может я не прав?

Ближе к сути.
Я Web-разработчик, по роду деятельности часто приходится делать AJAX запрос чтобы получить дополнительные данные. Так вот, для меня, - все AJAX запросы это API, а соответственно ответ должен быть такого типа:
{"code":1, "message":"username is required", "result":[....]}
где:
- code - код ответа. 0 - нет ошибок, можешь выбирать данные из респонса и работать с ними; 1,2,3 - другой код ошибок, и соответствующая реакция.
- message - описание ошибки или success если все ок.
result - может отсутствовать, например если ошибка или если не нужен ответ.

Тимлид говорит, есть API для внешнего использования и AJAX для внутреннего потребления, где не нужен строгий формат ответа. В итоге после получения ответа

$.post("...", function(data_arr){
    if('error' in data_arr){
	...
    }else{
        ...
    }
})


идет банальная проверка есть ли атрибут error и если есть, вывод. А если нет, то значит все ок. И каждый такой запрос разного формата ответы отдает (понятно что более-менее все одинаково, но все же),

Отсюда вопросы:
1. Правда что не всегда нужно делать API для мелкого подзапроса, и это не API а просто AJAX какая-то подгрузка данных?
2. Ведь правильно использовать всегда единый стандарт ответа, даже если это не полноценный API а мелочь?
  • Вопрос задан
  • 1483 просмотра
Пригласить эксперта
Ответы на вопрос 8
IvanVorobei
@IvanVorobei
iOS разработчик, ещё интерфейсы дизайню
Полиции нравов, которая проверит ваш АПИ и даст срок, нету. Тимлид может делать как угодно.
Но для внутреннего использования не нужно придумывать костыли. Формат, который предложил тимлид, не упрощает жизнь и не выглядит удобным.

P.S. Параметр code выглядит очень странно, есть коды ответа - используйте.
Ответ написан
Alex_Wells
@Alex_Wells
PHP/TS/Kotlin developer
Нет, не "должен", но может. Лично я пришел к такой схеме:
- 200-ые статус коды отправляются ТОЛЬКО тогда, когда все прошло успешно. В таком случае не будет никаких success: true или response: {} - а нужные данные, прямо на первом уровне нестинга. Собственно если взять за правило, что 200-ые коды возвращаются когда все ок, то можно полностью избавлятся от этих плохих проверок на наличие ключа в респонсе.
- 400-ые и 500-ые будут попадать в отдельный колбек/реджектить промис, опять же избавляя от нужды проверять какие-то ключи. Для всех кодов ответов, кроме 400 и 422 - в ответе нету нихрена. Ни code, ни message, ни response. Вообще ничего. Вся инфа находится в самом http status коде. Для 400 и 422 прибавляется параметр code, который является номером ВНУТРЕННЕЙ ошибки (ну, например, есть какие-то предусловия для выполнения запроса - уникальность эмейл адреса при регистрации как пример) - по ней фронт может показывать отдельные ошибки либо выполнять какую-то логику.

Плюс ко всему этому у себя локально и на сервере для фронта включен дебаг, добавляющий некий параметр _debug к каждому ответу. В нем может хранится любая инфа - сообщение с ошибкой (даже если ее можно понять по http коду или внутреннему), стак трэйс 500-ой ошибки и тд.
Ответ написан
@karminski
Разработчик CRM/ERP систем
Так вот, для меня, - все AJAX запросы это API

В этом ваша ошибка. Аякс это далеко не апи! Аякс это всего лишь асинхронный запрос к серверу. А что там на сервере - это другое дело.

Апи можно дергать как Аяксом, так и curl и другими методами.
Ответ написан
@ffosters
То, что API будет использоваться для внутренних целей не означает, что там может быть "бардак". Правильно было бы изначально договориться о формате, который будет использоваться в вашей команде.

Если соглашений нет, или возникают споры - есть некоторые общепринятые стандарты:


Так же посмотрите OpenAPI, RAML, API Blueprint
Ответ написан
mindtester
@mindtester
делаю странные вещи..чаще на C#.. иногда за деньги
просто в копилку https://habr.com/ru/post/441854/
(в остальном поддержу предыдущие ответ)
Ответ написан
Robur
@Robur
Знаю больше чем это необходимо
Что вы наваяете - то и будет вашим API. Хоть рандомные поля возвращайте.

То что вы привели как аргументацию тимлида - выглядит так себе. Апи для "внутреннего" использования отличается не тем что оно не строгое и там можно развести бардак, а тем что его менять проще и быстрее.

Однако делать так как говорит тимлид - возвращать {error: '...'} если ошибка, и {/*всякие данные в зависимости от запроса*/} если все ок - совершенно нормальная практика, и ничего плохого в этом нет. главное чтобы поле error не попалось в каком-то ответе, это по сути ваше единственное ограничение. Считайте что вы используете union types с детерминатором по наличию поля error, если вам хочется высоких формальностей и успокойтесь :)
Ответ написан
@nrgian
API в широком смысле - это всего лишь способ доступа извне.
Он может быть абсолютно любым. Лишь бы это был способ доступа извне.
Ответ написан
Jump
@Jump
Системный администратор со стажем.
Не путайте теплое с мягким.
AJAX - методика создания запроса.
API - информация о том какой запрос и в каком формате нужно отправить чтобы получить требуемый ответ.

Правда что не всегда нужно делать API для мелкого подзапроса, и это не API а просто AJAX какая-то подгрузка данных?
Делать API это значит писать документацию о том какими запросами и в каком формате из вашего сервера можно получить нужные данные.
Если вам это не нужно - можете ее не писать.

Ведь правильно использовать всегда единый стандарт ответа, даже если это не полноценный API а мелочь?
Непонятно что такое мелочь. Полноценный АPI это документация в которой описаны правила запросов. А уж по какому вы стандарту ее разрабатываете ваше дело.
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы