Лучшие Практики Использования RESTful API. Начало
Сегодня рассмотрим лучшие практики, которые можно использовать при работе с RESTful API.
1. Используйте JSON
В наши дни JSON является общепринятым стандартом для взаимодействия с API. Это предпочтительный выбор по сравнению с XML, поскольку он значительно снижает полезную нагрузку, что приводит к более быстрой передаче данных. Следовательно, ваши REST API должны использовать JSON для связи между клиентом и сервером. Обратите внимание, что REST не зависит от формата, что означает, что вы можете использовать любой формат для обмена данными, например XML, HTML, JSON и даже пользовательские форматы. Чтобы гарантировать, что ваш REST API обменивается данными в JSON, вы можете задать заголовок ответа
Content-Type: application/json.2. Версионирование
Версионирование - это процесс управления изменениями в API. Рекомендуется всегда добавлять версии в свой API. При разработке REST API следует помнить, что изменения неизбежны. Возможно, вам придётся внести критические изменения, чтобы удовлетворить потребности клиентов.
Такое критическое изменение может потребоваться из-за изменения формата данных ответа, изменения типа ответа, введения новых функций, редактирования или удаления существующих функций и т. д. Следовательно, крайне важно, чтобы у вас была стратегия реализации изменений.
Версионирование - одна из таких стратегий. Существуют разные варианты реализации версионирования API:
- URI
Это простейшая стратегия передачи информации о версии: поместить номер версии в путь URI. При этом по соглашению номер версии начинается с префикса «v»:
http://www.mywebsite.com/api/v1.0/products- Параметр запроса
http://www.mywebsite.com/api/v2.1/orders
Вы можете указать информацию о версии в параметре запроса. При этом базовый URL останется прежним:
http://www.mywebsite.com/api/products/{id}?version=1.0
Это более гибкий подход к запросу версии ресурса.- Заголовок запроса
Ещё один вариант - использовать заголовок Accept:
Accept: version=1.0В этом случае вам не нужно вносить никаких изменений в URL-адрес.
3. Документация
API неполон без надлежащей документации. Документация должна быть общедоступной и содержать сведения о конечных точках API и циклах запроса/ответа. Помните, что после того, как ваш API станет общедоступным, вы не должны вносить изменений без уведомления.
4. Всегда используйте SSL
Всегда используйте SSL. Здесь вообще не может быть никаких исключений. К вашему API можно получить доступ практически из любого места, где есть подключение к Интернету. Следовательно, вы должны убедиться, что ваши API безопасны. Связь между сервером и клиентом, использующим ваш API, должна быть защищённой и зашифрованной.
Окончание следует…
Источник: https://www.developer.com/web-services/best-practices-restful-api/