Blank page

Советы по проектированию REST API

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

Используйте стандартные методы HTTP для обозначения действия с запросом

Методы HTTP

Элементарные глаголы вносят ясность в то, что мы делаем вместе с этим запросом. Вот они:

GET, как понятно из названия (с англ. «получить»), используется для получения представления ресурса. Если все ОК, то GET возвращается представление ресурса в формате XML/JSON в сочетании с кодом состояния HTTP 200. При проблемах выскакивает код 404/400.
PUT предоставляет возможность обновления ресурса. Также PUT используется для создания ресурса, когда идентификатор ресурса выбирает клиент, а не сервер.
POST нужен для создания новых ресурсов. Если все ОК, то возвращается код 201, в заголовке Location передается адрес созданного ресурса.
DELETE используется для удаления ресурса - тут все просто). Если все ОК, как и в случае с GET получаем код 200.

2. Подумайте над именами ресурсов

Не следует брать названия с потолка – вот несколько правил, которые помогут создать для ресурса читаемое, понятное имя.

Имя ресурса должно быть существительным. За действие уже отвечает метод HTTP. Исключение – ресурсы-контроллеры, но это уже отдельная тема.

Плохой пример: /get_orders

Хороший пример: /orders

Следите за грамматическим числом (единственным или множественным). В единственном обозначают отдельные объекты, во множественном – коллекции, хранилища.
Лучше избегать сочетания слов и по возможности заменять их.

Плохой пример: /category_list

Хороший пример: /categories

Путь должен быть как можно короче, содержать как можно меньше слов.
Для обозначения иерархии нужно использовать слэш (/). Однако завершающий слэш будет лишним и внесет путаницу.

Плохой пример: /company/employee/

Хороший пример: /company/employee

Используйте буквы в нижнем регистре, потому что URI чувствительны к регистру.

Плохой пример: /Company/EMPLOYEE

Хороший пример: /company/employee

3. Детализируйте ошибки, пользуясь кодами состояний HTTP-ответов

Коды состояний – часть спецификации HTTP. Они помогут быстро идентифицировать ошибку. Запомнить их легко – это всегда трехзначное число, и первая цифра обозначает категорию состояния. Всего их 5:

1xx – информация о процессе передачи. Например, 101 обозначает переключение протоколов.
2xx – успех при выполнении запроса. Код 200 означает, что запрос успешно выполнен. Далее идут более детальные коды: например, 201 означает успешное создание ресурса после запроса POST.
3xx – перенаправление. Коды сообщают, что пользователь должен сделать запрос по-другому URI, чтобы успешно его выполнить. Сервер подскажет адрес (location), по которому нужно сделать запрос.
4xx – ошибка клиента. Означает, что пользователь совершил ошибку при запросе. Например, 401 появляется, когда клиент не авторизован в системе, а 405 – использован неправильный метод (например, вместо GET – POST).
5xx – ошибка сервера. В этом случае клиент все сделал правильно, а сервер недоступен, не вернул ответ или с ним случилось что-то еще

4. Подумайте, какой формат данных использовать – JSON или XML

Разница между XML и JSON

JSON и XML – два наиболее популярных формата передачи данных. Вместо тысячи слов про отличия – взгляните на картинку.
XML – это язык разметки, подобный HTML. Более стандартизированный формат, имеет сведения о пространстве имен и валидации. Используется в SOAP API и в тех областях, где важно иметь строго структурированные данные: например, компания Microsoft активно использует XML в большей части своей продуктов.
А если потребности в строгой структуре, сведениях о пространстве имен и других особенностях XML нет, лучше использовать JSON. Формат построен по типу «ключ-значение», его гораздо проще читать, он более лаконичен и быстрее обрабатывается. А еще его проще проектировать.

5. Помните про связанность через ссылки

It is necessary to choose a visual aid that is appropriate for the topic and audience.

Связанность через ссылки – это один из принципов REST, но им зачастую пренебрегают. API спокойно существует без ссылок, но с ними конечные точки становятся более информативными и самоописательными.
Как мы знаем, сущности имеют связи. Например, сущности «книга» и «автор» будут связаны, так как автор написал книгу. В БД их взаимосвязь отображается с помощью ключей – у книги внешним ключом будет идентификатор автора.
Однако на уровне API пользоваться этими ключами не совсем удобно – они малоинформативны и усложняют работу клиенту. Но если представить это взаимоотношение с помощью ключей, то сокращается количество связанностей между клиентом и сервером. Клиенту будет легче работать с API, так как он сможет просто преобразовать строку с ссылкой в API, и ему не потребуется более конкретная информация об API проекта в целом.

Получить практику по проектированию rest API

Вы можете получить на нашем курсе

Записаться