10 лучших практик для разработки REST API

Лучшие практики разработки REST API для обеспечения максимально возможной производительности.

REST API, акроним для репрезентативной передачи состояния, представляет собой архитектурный стиль для распределенных систем гипермедиа. Это гибкий метод разработки API в соответствии с определенным протоколом.

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

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

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

Рекомендации по оптимизации вашего REST API

1. Используйте JSON для отправки и получения данных

Хорошо спроектированный REST API всегда должен принимать и получать данные в формате JSON.

JSON — это облегченный формат обмена данными, ставший стандартом для многих разработчиков. Он доступен во многих технологиях и делает кодирование и декодирование быстрым и простым на стороне сервера благодаря своей легкости. Кроме того, JSON легко читается и интерпретируется.

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

Чтобы убедиться, что REST API использует формат JSON, всегда устанавливайте Content-Type в заголовке ответа на application/JSON. Большинство серверных фреймворков имеют встроенные функции для автоматического анализа данных в формате JSON.

2. Используйте существительные вместо глаголов

Соглашения об именах для REST API важны и могут избавить вас от путаницы.

Мы никогда не должны использовать такие глаголы, как DELETE, PUT или GET в наших конечных точках API, поскольку они аналогичны стандартным методам HTTP-запроса. Кроме того, существительное, используемое для API, уже точно описывает объект, которым манипулируют.

Однако, когда мы хотим обратиться к глаголам, мы в основном обращаемся к методам HTTP, таким как GET, POST, PUT и DELETE. Они напоминают операции CRUD, происходящие на уровне базы данных, которые мы не хотим интегрировать непосредственно в именование API.

Предположим, нам нужно получить список пользователей. Мы назовем API следующим образом:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());
app.get('/user’, (req, res) => {
  const user’= [];
  res.json(user);
});

//Avoid this.
aap.get(‘getUser’, req,res)=>{
  const user’= [];
  res.json(user);
});

3. Используйте множественное число для коллекций

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

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

// (List of users)
https://api.abc.com/users

Неправильная конечная точка будет выглядеть так:

https://api.abc.com/user

4. Не игнорируйте обработку ошибок

Каждое приложение подвержено ошибкам, поэтому обработка ошибок так важна. Хороший API должен всегда возвращать надлежащий код ошибки HTTP, который правильно объясняет природу конкретной возникшей ошибки.

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

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
// existing users
const users = [
  { email: '[email protected]' }
]
app.use(bodyParser.json());
app.post('/users', (req, res) => {
  const { email } = req.body;
  const user= users.find(u => u.email === email);
  if (user) {
    return res.status(400).json({ error: 'User already exists' })
  }
  res.json(req.body);
});
app.listen(3000, () => console.log('server started'));

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

5. Фильтруйте данные

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

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

6. Обеспечьте надежную защиту

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

Поскольку данные иногда содержат конфиденциальную информацию, такую ​​как данные кредитной карты, мы должны обеспечить полную конфиденциальность связи между сервером и клиентом. Безопасность SSL/TLS — это распространенный и доступный способ убедиться, что каждый запрос и ответ шифруются по каналам.

Кроме того, пользователь не должен иметь доступа к большему количеству данных, чем необходимо. Например, доступ пользователя А к данным пользователя Б представляет огромную угрозу конфиденциальности и безопасности. Один из способов решить эту проблему — предоставить администраторам их собственные привилегии и назначить роли пользователям индивидуально.

7. Автоматизируйте кэширование

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

Однако может возникнуть одна проблема: данные могут устареть. Для этого существует несколько стандартных решений для кэширования, которые могут кэшировать данные после каждого изменения, таких как Redis и Amazon ElasticCache.

8. Назначьте правильную версию API

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

Цель состоит в том, чтобы обеспечить наилучшее взаимодействие с пользователем, оставив обновления необязательными для клиентов. Обычной практикой является добавление версии перед конечной точкой следующим образом:

https://api.abc.com/v1/users
https://api.abc.com/v2/users

9. Используйте вложение для отображения отношений

Объединение связанных конечных точек для создания иерархии называется вложением API. Например, если у пользователя есть какие-либо активные заказы, то вложение /order после /users/:id является хорошим способом управления API:

https://api.abc.com/users (list of users)
https://api.abc.com/users/321 (specific user by using filters)
https://api.abc.com/users/321/order (list of the order of the specific user)

Рекомендуется использовать меньше уровней вложенности, чтобы не усложнять приложение; вы можете использовать фильтрацию, чтобы уменьшить количество уровней вложенности. Двухуровневая вложенность обычно делает API проще и выполняет свою работу.

10. Предоставьте документацию по API

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

Документация Solid API должна включать следующие характеристики:

• Простая формулировка и язык
• Объяснение запроса, пример и образцы ответов для каждой конечной точки.
• Реализация API на разных языках программирования (если применимо)
• Зачислены возможные сообщения об ошибках

Заключение

По мере увеличения интернет-трафика с каждым днем ​​извлекается все больше и больше данных. Хороший API — это основа любой системы, обеспечивающая бесперебойную работу. Если мы будем следовать приведенным выше рекомендациям при разработке наших API, результатом будут высокофункциональные и производительные приложения.

Дополнительные материалы на PlainEnglish.io. Подпишитесь на нашу бесплатную еженедельную рассылку новостей. Подпишитесь на нас в Twitter и LinkedIn. Посетите наш Community Discord и присоединитесь к нашему Коллективу талантов.