Может ли быть 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 а мелочь?
  • Вопрос задан
  • 1441 просмотр
Пригласить эксперта
Ответы на вопрос 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 и другими методами.
Ответ написан
mindtester
@mindtester
делаю странные вещи..чаще на C#..иногда за деньги
просто в копилку https://habr.com/ru/post/441854/
(в остальном поддержу предыдущие ответ)
Ответ написан
@ffosters
То, что API будет использоваться для внутренних целей не означает, что там может быть "бардак". Правильно было бы изначально договориться о формате, который будет использоваться в вашей команде.

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


Так же посмотрите OpenAPI, RAML, API Blueprint
Ответ написан
Robur
@Robur
Знаю больше чем это необходимо
Что вы наваяете - то и будет вашим API. Хоть рандомные поля возвращайте.

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

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

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

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

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

Войти через центр авторизации
Похожие вопросы
UMA.TECH Москва
от 150 000 до 215 000 руб.
MGCom Москва
от 120 000 до 140 000 руб.
СИМФОСОФТ Москва
от 130 000 руб.
24 июн. 2019, в 18:52
40000 руб./за проект
24 июн. 2019, в 18:44
5000 руб./за проект
24 июн. 2019, в 17:46
5000 руб./за проект