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

Question

[seredaes]

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

Ближе к сути.
Я 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 а мелочь?

Comments

[Adamos]

error или запрошенные данные - это, вообще-то, тоже единый стандарт.
Накручивать вокруг него оверхед, который никем и никогда не будет использоваться - смысл?

[Евгений Ромашкан]

Разберитесь что такое API, не стыдно своё невежество публично выставлять?

[Сергей Рогожкин]

В Go при меппинге структуры на json есть опция omitempty - если значение непустое, оно кодируется в json иначе поля нет. И это очень распространенная практика, когда поля "ошибка" и "код", "описание ошибки" возникают только при наличие таковых. Например в Telegram Bot API. Если разные структуры приходят на одни и те же виды запросов(без учета опциональных ошибок) - это немного диковато. Потому что на клиенте было бы логично описать какой-то фиксированный набор структур и делать меппинг результатов вызова на структуру. В PHP это не представляет проблемы, массив и в Африке массив, а в более строгих языках структура ответа по конкретному запросу как правило должна быть формализована.

Answer 1

[Иван Воробей]

Полиции нравов, которая проверит ваш АПИ и даст срок, нету. Тимлид может делать как угодно.
Но для внутреннего использования не нужно придумывать костыли. Формат, который предложил тимлид, не упрощает жизнь и не выглядит удобным.

P.S. Параметр code выглядит очень странно, есть коды ответа - используйте.

Comments

[Макс]

коды ответа это уровень http-протокола, а не информация о состоянии данных. Не нужно смешивать уровни абстракции

[Иван Воробей]

Maxim, согласен.

Answer 2

[Alex Wells]

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

Плюс ко всему этому у себя локально и на сервере для фронта включен дебаг, добавляющий некий параметр _debug к каждому ответу. В нем может хранится любая инфа - сообщение с ошибкой (даже если ее можно понять по http коду или внутреннему), стак трэйс 500-ой ошибки и тд.

Answer 3

[Антон Иванов]

Так вот, для меня, - все AJAX запросы это API

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

Апи можно дергать как Аяксом, так и curl и другими методами.

Answer 4

[bkosun]

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

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

• JSON API
  
• JSend
  
• OData JSON Protocol
  
• JSON API
  
• JSON-RPC
  
• ...
  

Так же посмотрите OpenAPI, RAML, API Blueprint

Answer 5

[#]

просто в копилку https://habr.com/ru/post/441854/
(в остальном поддержу предыдущие ответ)

Comments

[Антон Швец]

RPC на один ендпойнт в девтулзах выглядят нечитабельно. REST предпочтительнее, просто сразу видишь его.

[#]

Антон Швец, даже не пытался его противопоставить, но расширить эрудицию, иногда полезно ))

[Сергей Рогожкин]

Антон Швец, классический REST выглядит как безумный нечитаемый набор урлов; на каждый запрос руками приходится писать человеческое описание, так что принципиальной разницы нет, сколько эндпойнтов.

Answer 6

[Robur]

Что вы наваяете - то и будет вашим API. Хоть рандомные поля возвращайте.

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

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

Answer 7

[nrgian]

API в широком смысле - это всего лишь способ доступа извне.
Он может быть абсолютно любым. Лишь бы это был способ доступа извне.

Answer 8

[АртемЪ]

Не путайте теплое с мягким.
AJAX - методика создания запроса.
API - информация о том какой запрос и в каком формате нужно отправить чтобы получить требуемый ответ.

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

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

Ведь правильно использовать всегда единый стандарт ответа, даже если это не полноценный API а мелочь?

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