[Разработка веб-сайтов, API] Как написать удобный API — 10 рекомендаций
Автор
Сообщение
news_bot ®
Стаж: 6 лет 3 месяца
Сообщений: 27286
Я разработчик и большую часть моей карьеры я строю API различных сервисов. Рекомендации для этой статьи, были собраны на основе наиболее часто встречающихся проблем при проектировании своего сервиса в команде или использовании сторонних API.Скорее всего вы сталкивались с провайдерами ужасного API. Работа с ними, как правило, сопряжена повышенной эмоциональностью и недопониманием. Большую часть таких проблем можно избежать проектируя интерфейс приложения используя советы ниже.1. Не используйте глаголы в URL ** - если это одна из CRUD-операций.За действие с ресурсом отвечают CRUD-методы запроса: POST - создать (create), GET - получить (read), PUT/PATH - обновить (update), DELETE - удалить (ну вы поняли). Плохо:
POST /users/{userId}/delete - удаление пользователя
POST /bookings/{bookingId}/update - обновление бронировки
Хорошо:
DELETE /users/{userId}
PUT /bookings/{bookingId}
2. Используйте глаголы в URLПлохо:
POST /users/{userId}/books/{bookId}/create - добавить книгу пользователю
Хорошо:
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send - отправить уведомление пользователю
3. Выделяйте новые сущностиВыше есть пример добавления книги пользователю, возможно, логика вашего приложения подразумевает список избранного, тогда роут может быть и таким:
POST /wishlist/{userId}/{bookId}
4. Используйте один идентификатор ресурса ** - если ваша структура данных это позволяет.Это значит если у вас есть записи вида один ко многим, например
бронь -> путешественники (booking->travellers), вам будет достаточно передавать в запросе идентификатор путешественника. Плохо:
# получение данных путешественника
GET /bookings/{bookingId}/travellers/{travellerId}
Хорошо:
GET /bookings/travellers/{travellerId}
Так же замечу что /bookings/travellers/ лучше чем просто /travellers хорошо придерживаться иерархии данных в своем API.5. Все ресурсы во множественном числеПлохо:
GET /user/{userId} - получение данных пользователя
POST /ticket/{ticketId}/book - бронирование билета
Хорошо:
GET /users/{userId}
POST /tickets/{ticketId}/book
6. Используйте HTTP-статусы по максимумуСамый простой способ обработки ошибок - это ответить соответствующим кодом состояния. В большинстве случает один этот статус может дать исчерпывающую информацию о результате обработки запроса. Одни из самых распространенных кодов ответов:
- 400 Bad Request - клиент отправил неверный запрос, например, отсутствует обязательный параметр запроса.
- 401 Unauthorized - клиенту не удалось пройти обязательную аутентификацию на сервере для обработки запроса.
- 403 Forbidden - клиент аутентифицирован, но не имеет разрешения на доступ к запрошенному ресурсу.
- 404 Not Found - запрошенный ресурс не существует.
- 409 Conflict - этот ответ отправляется, когда запрос конфликтует с текущим состоянием сервера.
- 500 Internal Server Error - на сервере произошла общая ошибка.
- 503 Service Unavailable - запрошенная услуга недоступна.
7. Модификаторы получения ресурсаЛогика построения роутов может быть не связана с архитектурой проекта или структурой базы данных. Например, в бд есть викторины и пройденные викторины - две отдельные таблицы (quizzes и passed_quizzes). Но для апи это могут быть просто викторины, а пройденные викторины это модификатор. Пример: /quizzes и /quizzes/passed. Здесь quizzes - ресурс (викторины), passed - модификатор (пройденные).Плохо:
GET /passed-quizzes - получение пройденных викторин
GET /booked-tickets - получение забронированных билетов
POST /gold-users - создание премиум пользователя
Хорошо:
GET /tickets/booked
POST /users/gold
8. Выберите одну структуру ответовКогда на два запроса к API может быть получен совсем разный по структуре ответ - это грустно. Старайтесь сформировать одну четкую структуру которой всегда будете придерживаться, будет круто еще включить служебные поля, несущие дополнительную информацию.Плохо:
GET /book/{bookId}
{
"name": "Harry Potter and the Philosopher's Stone",
"genre": "fantasy",
"status": 0, # статус вашего приложения
"error": false,
...
}
Хорошо:
GET /book/{bookId}
{
"status": 0,
"message": "ok",
"data": {...}
}
В этом примере 3 поля универсальны и могут использоваться для любого ответа от апи. status, message - собственный статус и сообщение приложения по которому клиент сможет ориентироваться, эти поля сообщат ему дополнительную информацию о процессе обработки запроса, но не данные ресурса. Например, в нашем приложении в один момент времени, пользователь может проходить только одну викторину. Тогда запрос на начало новой может выдать 409й статус а в полях status и message дополнительную информацию почему была получена ошибка.9. Все параметры и json в camelCase9.1 В параметрах запросов
Плохо:
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
Хорошо:
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2 В теле ответа или принимаемого запроса
Плохо:
{
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"provider_id": 1455,
"Created_At": "25.05.2020"
}
Хорошо:
{
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"providerId": 1455,
"createdAt": "25.05.2020"
}
10. Пользуйтесь Content-TypeПлохо:
GET /tickets.json
GET /tickets.xml
Хорошо:
GET /tickets
// и в хедере
Сontent-Type: application/json
// или
Сontent-Type: application/xml
ЗаключениеПеречисленные выше рекомендации это далеко не весь список способов сделать API лучше. Для дальнейшего изучения рекомендую разобрать спецификации REST API и список кодов http-статусов (вы удивитесь на сколько их много и какие ситуации они охватывают).А в комментариях, предлагаю написать свою рекомендацию по построению REST API которую вы считаете важной.
===========
Источник:
habr.com
===========
Похожие новости:
- [.NET, C#, Data Engineering] One of the ways to dynamically deserialize a part of a JSON document with an unknown structure
- [Разработка веб-сайтов, JavaScript, Программирование, GitHub, Игры и игровые приставки] Разработчик сделал Doom Captcha — теперь можно проходить тест на робота играя
- [Научно-популярное, Космонавтика] Начинается космическая эпоха ISRU
- [Разработка веб-сайтов, Проектирование и рефакторинг, Хранение данных] Может поменять способ хранения?
- [Законодательство в IT, Финансы в IT, IT-компании] Инвесторы Da Vinci Capital подали иск против Telegram
- [Разработка веб-сайтов, Разработка мобильных приложений, Карьера в IT-индустрии] Без тимлида не обойтись, а что насчет техлида?
- [Программирование, Компиляторы, Функциональное программирование, Искусственный интеллект] Тестирование синтаксиса языка программирования с необычной концепцией
- [Мессенджеры, Платежные системы, Python, API] Как принимать платежи в Telegram | API Yoomoney Python
- [Веб-дизайн, Разработка веб-сайтов, CSS] Взгляд на Tailwind CSS (перевод)
- [Amazon Web Services, Angular, DevOps] Сам себе DevOps: строим cloud-only CI для веб приложения
Теги для поиска: #_razrabotka_vebsajtov (Разработка веб-сайтов), #_api, #_api, #_web, #_rest_api, #_json, #_xml, #_razrabotka_vebsajtov (
Разработка веб-сайтов
), #_api
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 15-Май 15:09
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 3 месяца |
|
|
Я разработчик и большую часть моей карьеры я строю API различных сервисов. Рекомендации для этой статьи, были собраны на основе наиболее часто встречающихся проблем при проектировании своего сервиса в команде или использовании сторонних API.Скорее всего вы сталкивались с провайдерами ужасного API. Работа с ними, как правило, сопряжена повышенной эмоциональностью и недопониманием. Большую часть таких проблем можно избежать проектируя интерфейс приложения используя советы ниже.1. Не используйте глаголы в URL ** - если это одна из CRUD-операций.За действие с ресурсом отвечают CRUD-методы запроса: POST - создать (create), GET - получить (read), PUT/PATH - обновить (update), DELETE - удалить (ну вы поняли). Плохо: POST /users/{userId}/delete - удаление пользователя
POST /bookings/{bookingId}/update - обновление бронировки DELETE /users/{userId}
PUT /bookings/{bookingId} POST /users/{userId}/books/{bookId}/create - добавить книгу пользователю
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send - отправить уведомление пользователю POST /wishlist/{userId}/{bookId}
бронь -> путешественники (booking->travellers), вам будет достаточно передавать в запросе идентификатор путешественника. Плохо: # получение данных путешественника
GET /bookings/{bookingId}/travellers/{travellerId} GET /bookings/travellers/{travellerId}
GET /user/{userId} - получение данных пользователя
POST /ticket/{ticketId}/book - бронирование билета GET /users/{userId}
POST /tickets/{ticketId}/book
GET /passed-quizzes - получение пройденных викторин
GET /booked-tickets - получение забронированных билетов POST /gold-users - создание премиум пользователя GET /tickets/booked
POST /users/gold GET /book/{bookId}
{ "name": "Harry Potter and the Philosopher's Stone", "genre": "fantasy", "status": 0, # статус вашего приложения "error": false, ... } GET /book/{bookId}
{ "status": 0, "message": "ok", "data": {...} } Плохо: GET /users/{user-id}
GET /users/{user_id} GET /users/{userid} GET /users/{userId}
POST /ticket/{ticketId}/gold Плохо: {
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec", "Name": "soccer3000", "provider_id": 1455, "Created_At": "25.05.2020" } {
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec", "Name": "soccer3000", "providerId": 1455, "createdAt": "25.05.2020" } GET /tickets.json
GET /tickets.xml GET /tickets
// и в хедере Сontent-Type: application/json // или Сontent-Type: application/xml =========== Источник: habr.com =========== Похожие новости:
Разработка веб-сайтов ), #_api |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 15-Май 15:09
Часовой пояс: UTC + 5