ℹ️ Прежде чем начать писать что-либо, я хотел бы упомянуть, что все это – мои личные мысли, основанные на моих знаниях, опыте и проблемах, с которыми я сталкивался в прошлом. ℹ️
Сейчас современный век Интернета, и существуют тысячи, если не миллионы сайтов, на которые мы натыкаемся. Сотни из них могут быть динамическими (т.е. получать данные каждый раз, когда мы запрашиваем их из какого-либо источника данных).
Весь процесс получения данных в большинстве случаев осуществляется через API (SOAP, REST или GraphQL).
Таким образом, API можно рассматривать как переводчика между двумя людьми, говорящими на двух разных языках. Только представьте, что произойдет, если переводчик переведет неправильно.
Что нужно учесть
Коммуникация – это ключ!
Поэтому есть много вещей, которые, на мой взгляд, следует учитывать при настройке API-ответов.
Не используйте объекты или массивы данных верхнего уровня
Раньше я думал, что легко просто отправить данные после их получения непосредственно из базы данных.
Например, отправить такой ответ на вызов API https://api.xyz.com/users/1.
{
"fullName": "Full Name",
"dateOfBirth": "2000-01-01"
}
Или, например, ниже для вызова API https://api.xyz.com/users
[
{
"fullName": "First User",
"dateOfBirth": "2000-01-01"
},
{
"fullName": "Second User",
"dateOfBirth": "1990-04-04"
}
]
Хотя возвращать данные таким образом будет легко, рано или поздно это вызовет огромную проблему.
Основная проблема заключается в том, что мы не можем добавить дополнительную информацию в первый объект ответа, и это даже невозможно во втором массиве ответа.
Используйте согласованную оболочку имен переменных
Существуют различные способы присвоения имени переменной:
- camelCase – популярный среди разработчиков JavaScript.
- snake_case – популярный среди разработчиков Python (snake_case для разработчиков Python… какое совпадение…).
- PascalCase
- kebab-case
Я думаю, что нет необходимости упоминать об этом, потому что разработчики, использующие конкретный язык, уже имеют свои собственные предпочтения по поводу регистра имен переменных.
От себя замечу, что использование нескольких корпусов имен в одном проекте – это большое НЕТ!
Если это возможно, я бы даже посоветовал каждому взять на вооружение один метод использования корпусов имен и следовать ему на протяжении всего пути программирования в жизни.
Используйте правильные имена переменных
Это относится не только к объекту ответа API, но и к самим кодам и сущностям базы данных.
Я уверен, что существуют тысячи статей/заметок о том, как должны быть написаны имена переменных, поэтому я не буду углубляться в эту тему, но я хотел бы приложить простое, но важное замечание по этому поводу:
Имя переменной должно быть “как можно короче, как можно длиннее”!
Решение
Простое, но эффективное решение для структуры ответа API заключается в том, чтобы просто иметь следующую структуру данных:
Например, отправляем такой ответ для вызова API https://api.xyz.com/users/1.
{
"message": "Successfully fetched User data",
"data": {
"fullName": "Full Name",
"dateOfBirth": "2000-01-01"
}
}
Или, например, ниже для вызова API https://api.xyz.com/users
{
"message": "Successfully fetch Users data",
"pagination": {
"page": 1,
"count": 2,
"perPage": 10
},
"data": [
{
"fullName": "First User",
"dateOfBirth": "2000-01-01"
},
{
"fullName": "Second User",
"dateOfBirth": "1990-04-04"
}
]
}
Возможно, вы уже заметили, что я могу отправить сообщение в ответе API. А во втором примере использования API я даже могу отправить детали пагинации.
Будут обрабатываться тысячи данных, поэтому пагинация, очевидно, рано или поздно будет сделана. Однако в предыдущем подходе мы не могли должным образом упомянуть о деталях пагинации. Мы решили эту проблему.
Теперь вы, возможно, зададитесь вопросом: не больно ли получать доступ к данным, проходя еще один уровень вглубь объекта? То есть response.data вместо response.
Ответ – да, но кроме этого недостатка, это единственный хороший момент, который я могу придумать.
Например, допустим, нам нужно ответить сообщением об ошибке, если запрос API недействителен. Следуя этому подходу, мы можем просто отправить ответ, например:
{
"message": "Invalid email address" // or any other error message
}
И теперь во фронтенде/мобильном приложении мы всегда можем обратиться к response.message, чтобы получить информацию об использовании API. А чтобы понять, был ли вызов API успешным или неудачным, мы можем использовать код состояния HTTP вызова API.
Основной момент
Основная мысль всего этого обсуждения заключается в том, что ответ APi никогда не должен быть объектом данных верхнего уровня.
Вместо этого используйте объект, который содержит всю информацию, которую вы хотите передать с сервера на фронтенд (не связанную с API).
А в объект верхнего уровня включите данные, связанные с вызовом API, в ключ result или data.
Это приведет к чистому и согласованному ответу API на каждой конечной точке API. Кроме того, вы сможете передавать дополнительную информацию, не относящуюся к конкретному вызову API.
Заключение
Я уже совершал эту ошибку в прошлом и получил тяжелые уроки. Но это не значит, что вы должны совершить эту ошибку сами, чтобы научиться.
Вы можете попробовать реализовать упомянутый мной подход в своем следующем проекте (или даже в текущем, если это возможно без серьезных ломающих изменений).
Если вы занимаетесь разработкой API, я хотел бы услышать ваши мысли об этом подходе и о том, хотите ли вы перейти на него (если еще не используете).
Если вы являетесь потребителем API, я хотел бы услышать ваши мысли о том, как это изменение (если это не то, что предоставляет ваш текущий API) повлияет на вас.
Если вы уже используете этот подход, то будьте здоровы, вы облегчаете жизнь себе и фронтенд-разработчику 😉.