ЛУЧШИЕ практики для дизайна REST API.

В этой статье мы рассмотрим, как создавать простые и понятные REST API.

Что такое ОТДЫХ?

REST - это аббревиатура от REpresentational State Transfer. Это архитектурный стиль для распределенных гипермедийных систем, впервые представленный Роем Филдингом в 2000 году.

REST API - это одни из наиболее часто используемых веб-сервисов в современном мире. Они позволяют браузерам и мобильным приложениям связываться с сервером.

Вот почему важен правильный дизайн REST API. Правильный дизайн помогает масштабировать и управлять нашими бэкэнд-сервисами. В противном случае мы создаем проблемы для клиентов, использующих наши API.

Мы обсудим несколько распространенных примеров дизайна. В этом руководстве мы будем использовать фреймворк NodeJS и ExpressJS.

Принять и ответить с помощью JSON

REST API должен принимать запрос JSON от клиента и отправлять ответ клиенту в формате JSON. JSON - это стандарт для передачи данных. В JavaScript есть встроенные методы для простого управления данными JSON.

Есть и другие способы передачи данных. XML не широко поддерживается фреймворками без преобразования самих данных во что-то, что можно использовать, и это обычно JSON.

Данные формы хороши для отправки данных, особенно для отправки файлов. Но текст и числа, нам не нужны данные формы. Большая часть фреймворка поддерживает отправку данных напрямую.

В нашем ответе REST API мы должны установить Content-Type в заголовке ответа на application/json после того, как запрос будет сделан. HTTP-клиенты, такие как мобильное приложение, анализируют ответ в соответствии с типом содержимого.

Мы также должны убедиться, что наши конечные точки возвращают JSON в качестве ответа. Многие серверные фреймворки имеют это как встроенную функцию.

Взгляните на пример:

В платформе Express мы используем body-parser промежуточное ПО для синтаксического анализа тела запроса JSON, а затем мы можем вызвать res.json() метод с объектом, который мы хотим отправить клиенту.

bodyParser.json() анализирует строку тела запроса JSON на объект JavaScript, а затем назначает его объекту req.body.

Установить заголовок Content-Type в ответе на application/json; charset=utf-8 без изменений. Вышеупомянутый метод применим к большинству других серверных фреймворков.

Используйте существительные для конечных точек

Мы должны использовать существительные для конечных точек, потому что существительные представляют сущности. Используя эти конечные точки, мы извлекаем данные или манипулируем ими.

В нашем коде методы HTTP-запроса уже содержат глаголы. Например, некоторым нравится «get», а некоторым - «retrieve», поэтому лучше позволить команде HTTP GET сообщать нам, что делает конечная точка.

Действие должно указываться с помощью метода HTTP-запроса, который мы делаем. Наиболее распространенные методы включают GET, POST, PUT и DELETE.

Глаголы соответствуют операциям CRUD.

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

Вложенные ресурсы для иерархических объектов

Путь конечных точек обрабатывает вложенные ресурсы, добавляя вложенные ресурсы в качестве имени пути, идущего после родительского ресурса.

Предположим, что если мы хотим получить комментарии к определенной статье, мы должны добавить /comment путь в конец пути /articles.

В приведенном выше примере мы можем использовать метод GET для получения всех комментариев по пути /articles/:articleId/comments.

Здесь comments - дочерние объекты articles.

Ошибка обработки

Мы должны правильно обрабатывать ошибки и возвращать правильный код HTTP-ответа конечным клиентам об ошибке.

Коды статуса HTTP-кода распространенной ошибки включают:

• 400 Bad Request - это означает, что ввод на стороне клиента не прошел проверку.
• 401 Unauthorized - это означает, что пользователь не авторизован для доступа к ресурсу. Обычно он возвращается, когда пользователь не прошел аутентификацию.
• 403 Запрещено - это означает, что пользователь аутентифицирован, но ему не разрешен доступ к ресурсу.
• 404 Not Found - это означает, что ресурс не найден.
• 500 Внутренняя ошибка сервера - это общая ошибка сервера. Вероятно, его не следует бросать явно.
• 502 Плохой шлюз - указывает на недопустимый ответ вышестоящего сервера.
• 503 Служба недоступна - это указывает на то, что на стороне сервера произошло что-то непредвиденное (это может быть что угодно, например, перегрузка сервера, отказ некоторых частей системы и т. Д.).

В приведенном выше коде у нас есть список существующих пользователей в массиве users с указанным адресом электронной почты.

Затем, если мы попытаемся отправить полезную нагрузку со значением email, которое уже существует в users, мы получим код состояния ответа 400 с сообщением 'User already exists', чтобы пользователи знали, что пользователь уже существует. Имея эту информацию, пользователь может исправить действие, изменив адрес электронной почты на несуществующий.

Разрешить фильтрацию, сортировку и разбиение на страницы.

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

В приведенном выше коде у нас есть req.query переменная для получения параметров запроса.

Согласно запросу, мы фильтруем результаты и отправляем ответ обратно клиенту.

Запрос:

/employees?lastName=Smith&age=30

Ответ:

[
    {
        "firstName": "John",
        "lastName": "Smith",
        "age": 30
    }
]

Примечание. Например, мы можем извлечь строку запроса из URL-адреса, например:

http://example.com/articles?sort=+author,-datepublished

Где + означает восходящий, а - означает нисходящий. Таким образом, мы сортируем по имени автора в алфавитном порядке и datepublished от самого последнего до самого раннего.

Данные кеша

Мы можем улучшить производительность API, кэшируя ответ в основную память вместо запроса в базу данных. Это улучшит производительность. Ответ доставлен быстрее.

Есть много видов решений для кэширования, таких как Redis, кэширование в памяти и другие. Мы можем изменить способ кэширования данных по мере изменения наших потребностей.

Например, в Express есть apicache промежуточное ПО для добавления кэширования в наше приложение без особой настройки. Мы можем добавить простой кеш в памяти на наш сервер следующим образом:

Версионирование наших API

Управление версиями обычно выполняется с добавлением /v1/, /v2/ и т. Д. В начале пути API.

app.get('/v1/employees', (req, res) => {
  const employees = [];
  // code to get employees
  res.json(employees);
});

app.get('/v2/employees', (req, res) => {
  const employees = [];
  // different code to get employees
  res.json(employees);
});

Спасибо!

Удачного кодирования!