1. Главная
  2. Блог
  3. Как спроектировать rest api

Как спроектировать rest api

Как спроектировать rest api
Автор
Анатолий Ахматов
На чтение
5:45 мин
Обновлено
06.08.2021

Приветствую друзья! В этой статье будет краткий мануал по проектированию интерфейса rest api, рассмотрим частые ошибки и используемые стандарты.

Поехали!

Версия api

Чтобы в дальнейшем не было проблем с поддержкой, рекомендуется разделять api по версиям. Сделать это можно добавив название мажорной версии в url

/api/v1/users/1

/api/v2/users/1

...
Лучше использовать версионирование api, чем не использовать

Правила именования роутов

Не используем слэш в конце url

Ко многим разделам вашего api могут идти дополнительные атрибуты, и не всегда интуитивно понятно что их можно добавить если на конце стоит закрывающий слэш

/api/v1/posts
/api/v1/posts/ // не верно

/api/v1/posts/categories
/api/v1/posts/categories/ // не верно

/api/v1/posts?offset=12
/api/v1/posts/?offset=12 // не верно

Именование во множественном числе

Старайтесь всегда называть разделы api во множественном числе, так как существуют слова употребляемые только во множественном числе (glasses, money, clothes), и чтобы в дальнейшем не было путаницы, лучше давать имена в одном стиле

/api/v1/posts
/api/v1/post // не верно

/api/v1/post/categories // не верно
/api/v1/posts/category // не верно
/api/v1/posts/categories

Выборка по id

Чтобы получить например, данные заказа, в api должно быть достаточно передать его id

/api/orders/(( id ))

/api/orders/1

Логическая цепочка

Для того чтобы api было интуитивно понятным, необходимо соблюдать логическую цепочку наименования разделов. К примеру нам нужно получить категории поста, логично сделать так 'Все посты -> конкретный пост -> категории'

/api/v1/posts/1/categories

/api/v1/categories/1 // не верно
/api/v1/categories?post=1 // не верно

Параметры запросов

Как правило параметры задаются в формате get в конце url. К примеру нам нужно получить только пять записей

/api/v1/posts?limit=5

/api/v1/posts/limit/5 // не верно

CRUD - create read update delete

С построением get(получить) запросов мы разобрались, теперь возмемся за создание, изменение, удаление данных. Здесь одним url не обойтись, нам нужны типы запросов POST, PUT, DELETE

Создание - post

Создание записей как правило производится POST запросом на необходимый раздел api, никаких /create/ /build/ /add/ в роуте прописывать не нужно, здесь идет фильтрация типа запроса

К примеру чтобы создать пост, нам нужно отправить POST запрос на подобный url

/api/v1/posts

/api/v1/posts/create // не верно

Чтение - GET

Стандартный get запрос на получение данных

Изменение - PUT

Как и в случае с созданием, url нам править не нужно, нужно только отфильтровать запрос по типу. Для изменения данных используется тип запроса PUT. Вот пример url для изменения поста запросом PUT

/api/v1/posts/1

Удаление - DELETE

Аналогично предыдущим, удаление производится только изменением типа запроса на DELETE

Все действия производятся только с помощью изменения запроса. Никогда не используйте глаголы в url

Ответ сервера

Сервер всегда должен возвращать http коды, вот стандартный список ответов сервера которые обязательно нужно реализовать

  • 200: Done, it was okay. // Обычно GET возвращает этот код.
  • 201: “Done, and created.” // Обычно POST возвращает этот код.
  • 204: “Done, and no body.” // Обычно DELETE возвращает этот код.
  • 400: “Client sent me junk, and I’m not going to mess with it.”
  • 401: “Unauthorized, the client should authenticate first.”
  • 403: “Not allowed. You can’t have it because you logged in but don’t have permission to this thing or to delete this thing.”
  • 404: “Can’t find it.”
  • 410: “Marked as deleted.”
  • 451: “The government made me not show it.”

Пример хорошего api блога

+--------+----------------------------------------+------------------------------------------------------+
|        | POST                                   | login                                                |
|        | POST                                   | logout                                               |
|        | POST                                   | password-recovery                                    |
|        |                                        |                                                      |
|        | GET                                    | posts?offset={n}&limit={n}                           |
|        | POST                                   | posts                                                |
|        | PUT                                    | posts                                                |
|        | DELETE                                 | posts                                                |
|        | GET                                    | posts/{n}/                                           |
|        | GET                                    | posts/{n}/categories                                 |
|        |                                        |                                                      |
|        | GET                                    | categories?offset={n}&limit={n}                      |
|        | POST                                   | categories                                           |
|        | PUT                                    | categories                                           |
|        | DELETE                                 | categories                                           |
+--------+----------------------------------------+------------------------------------------------------+
		

😁 Мой личный блог в вк:

Подписывайся

🥶 Из за чего WORDPRESS может быть «ДОЛГИМ»?

Помните волну курсов по типу «Как создать сайт на WP без навыков программирования?»

Лет 5 назад люди осознали что с помощью плагинов можно навесить на свой сайт кучу полезных функций, а еще есть плагины ускорения, а еще SEO оптимизации:

Перейти в вк

Со школы у меня мало воспоминаний, но одно есть и очень яркое. Как фильм, в нем есть все: драма, девушка, удар током)

И так, по порядку: дело было классе в 5, мне, как ребенку из малоимущей семьи предложили возможность бесплатно поехать в лагерь.

Мама собрала все нужные доки. И вот я еду, в свой первый лагерь) Со мной поехала красивая девочка Аня из параллели (до этого были не знакомы), тоже по такому же набору бумажек) Больше никого знакомого.

Перейти в вк

📔 У вас тоже бывает такое? Читаешь книгу, спустя примерно половину, начинаешь в жизни разговаривать как писатель

Позвать друга в бильярд:

Сударь, какая нынче дивная погода… нам стоит пройтись по мощёной серым кирпичем мостовой, испить чудестного напитка с привкусом потерянной любви и провести с наслаждением 2 часа за игрой в бильярд, прежде чем уйти в закат…

Перейти в вк

Также может понравится

Ремаркетинг на facebook: как создавать пользовательские аудитории и привлекать посетителей

Вот пошаговое руководство по использованию ремаркетинга Facebook для создания по
Показать полностью...

A/B Тестирование

Платный поиск - это все о постепенной оптимизации. Вы собираете данные, когда за
Показать полностью...

Как создать похожую аудиторию на facebook и расширить свой охват

Вот все необходимое, что вам нужно знать, от создания пользовательской аудитории
Показать полностью...

Почему хакеры любят WordPress

Хакеры любят WordPress, потому что это растущая система CMS номер один, и причин
Показать полностью...

Над веб-дизайном сгиба: Имеет ли это значение?

Знаете ли Вы, Почему Ваш Основной Призыв к действию на Веб-сайте Должен быть Выш
Показать полностью...

Как избежать усталости от принятия решений на веб-сайте

Предлагая слишком много вариантов на своем сайте, вы можете создать "усталость о
Показать полностью...