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

Что такое RESTful API?

REST является аббревиатурой от RE презентационного S tate T ransfer и описывает архитектурный стиль для создания распределенных веб-сервисов. REST позволяет пользователям использовать стандартные HTTP-запросы для удаленного вызова кода и получения ответов. REST имеет несколько преимуществ перед другими протоколами:

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

(Если создание RESTful API для вас ново или вам нужна песочница, чтобы опробовать эти передовые методы, попробуйте эту эталонную архитектуру от Heroku, которую можно быстро и легко развернуть.)

Итак, вот пять лучших рекомендаций по созданию ваших RESTful API.

1. Используйте коды состояния ошибки

В HTTP уже встроено более 100 кодов состояния. Использование кодов состояния в вашем RESTful API для сообщения об общей ошибке - находка для разработчиков. Разработчики смогут сразу определить проблему, а это значит, что они будут тратить меньше времени на написание парсеров для обработки всех различных типов ошибок. Запрос отклонен, потому что сеанс не вошел в систему? Для этого есть код статуса. Есть ли недостающий ресурс? Служба CRUD получила запрос, но не смогла подключиться к базе данных? Существуют коды состояния для них и почти для любого другого обычного поведения. Коды состояния также можно комбинировать с конкретными сообщениями об ошибках, чтобы предоставить подробную информацию о неудачных запросах.

Вот фрагмент кода из API Node.js для иллюстрации:

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

2. Хорошая документация

Документация - один из наиболее важных и наиболее часто игнорируемых аспектов API. Официальная документация может быть первой точкой контакта клиента с продуктом и ключевым фактором при принятии ее командой разработчиков. Хорошая документация выглядит чистой и последовательной и хорошо подготавливает разработчика к быстрому использованию вашего API. Чем быстрее кто-то сможет изучить ваш API, тем быстрее они начнут работать с ним. Документация должна иметь единообразный вид и включать всю необходимую информацию: конечную точку, совместимые методы (GET, POST, PUT и т. Д.), Какие параметры являются необязательными и обязательными, а также ожидаемый тип данных.

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

Документация API Heroku чиста, организована и дает разработчикам все необходимое.

3. Ограничение скорости и дросселирование

Запросы API могут быть ресурсоемкими, требовать серьезных вычислительных мощностей и хранилища. Если вы не будете осторожны, большое количество последовательных одновременных запросов может замедлить работу вашего сервера или даже отключить его. Простой способ сделать это - использовать один из множества доступных инструментов, таких как express-rate-limit, Express промежуточное ПО, разработанное специально для простой и интуитивно понятной обработки ограничения скорости. Вы также можете реализовать логику ограничения скорости, связанную с аутентификацией, что обеспечивает большую гибкость в управлении разрешениями, предоставляемыми каждому пользователю. Требуя от пользователей аутентификации, можно отслеживать количество запросов, отправляемых каждым пользователем, что также позволяет ограничивать или останавливать эти запросы. Разным пользователям также может быть предоставлен доступ к разным конечным точкам API. Например, пользователь, являющийся администратором, может получить доступ к большему количеству информации или большему количеству запросов из API, чем обычный непривилегированный пользователь. Еще одно преимущество использования аутентификации - это безопасность, которую она обеспечивает, что позволяет нам перейти к следующему передовому опыту.

4. Защитите API

API должны быть безопасными! Хакеры используют автоматизированные сценарии для неизбирательных атак на службы, поэтому API должен иметь упреждающие меры безопасности для обеспечения бесперебойной работы операций и защиты конфиденциальных данных. Прежде всего, каждое веб-приложение должно иметь политику HTTP Strict Transport Security (HSTS), чтобы гарантировать, что все соединения зашифрованы. Защита соединения предотвращает перехват сети, атаки типа злоумышленник в середине, атаки на более раннюю версию протокола и захват сеанса с помощью кражи файлов cookie. Вы также можете установить и скрыть определенные заголовки, которые могут быть использованы, например те, которые раскрывают информацию о вашей инфраструктуре API, которая может быть полезна злоумышленникам. Есть много инструментов, которые могут с этим справиться. Например, если вы используете API с Node.js, вы можете использовать что-то вроде Helmet.js. Реализовать это промежуточное ПО легко:

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

5. Используйте JSON.

Назначение API - предоставление данных из ресурсов вашей компании. Существует три формата, которые обычно используются для возврата данных согласно скандинавским API: XML, YAML и JSON.

XML легко читается человеком, но данные содержатся в наборе тегов разметки, который быстро увеличивается в размере и требует дополнительной полосы пропускания. Разработчики также должны анализировать содержимое тегов для доступа к данным.
YAML, напротив, использует очень небольшую полосу пропускания, но для работы с данными требуется либо внешняя библиотека, либо пользовательский синтаксический анализатор и кодировщик.
JSON прекрасно сочетает в себе миры XML и YAML: он удобен для чтения человеком, не требуя высокой пропускной способности или специального синтаксического анализа для перемещения данных в структуру, совместимую с JavaScript.

Заключение

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