По вашему запросу ничего не найдено :(
Убедитесь, что запрос написан правильно, или посмотрите другие
наши статьи:
Современные предприятия во многом доверяют технологии контейнеризации, чтобы упростить развертывания сложных приложений и управление ими.
Контейнеры собирают необходимые зависимости внутри одного пакета. Таким образом, вам не нужно беспокоится о том, что возникнут какие-либо конфликты зависимостей в эксплуатационной среде.
Контейнеры можно переносить и масштабировать, но для последнего маневра вам понадобится инструмент управления контейнерами.
На сегодняшний день Docker Swarm и Kubernetes – самые популярные платформы для оркестрации контейнеров. Они оба имеют свое конкретное назначение и определенные преимущества и недостатки.
В данной статье мы рассмотрим оба из них, чтобы помочь в выборе инструмента управления контейнерами с учетом ваших требований.
Что такое Docker Swarm?
Docker Swarm – это платформа оркестрации контейнеров с открытым исходным кодом, встроенная в Docker. Он поддерживает оркестрацию кластеров механизмов Docker.
Docker Swarm преобразует несколько экземпляров Docker в один виртуальный хост. Кластер Docker Swarm обычно состоит из трех элементов:
Node - нода
Service и Task – службы и задачи
Load balancer - балансировщик нагрузки
Ноды – это экземпляры механизма Docker, контролирующие ваш кластер, а также контейнеры, используемые для запуска ваших служб и задач.
Балансировка нагрузки также является частью кластеров Docker Swarm и используется для маршрутизации запросов между нодами.
Преимущества Docker Swarm
Docker Swarm довольно прост в установке, поэтому он хорошо подходит для тех, кто только начинает осваивать мир оркестрации контейнеров.
Он легковесный.
В контейнерах Docker Swarm обеспечивает автоматическую балансировку нагрузки.
Поскольку Docker Swarm встроен в Docker, то он работает с интерфейсом командной строки Docker. Помимо этого, он без проблем работает с существующими инструментами Docker, такими как Docker Compose.
Docker Swarm обеспечивает рациональный выбор нод, что позволяет выбрать оптимальные ноды в кластере для развертывания контейнера.
Имеет собственный Swarm API.
Недостатки Docker Swarm
Не смотря на множество преимуществ, Docker Swarm имеет также несколько недостатков.
Docker Swarm сильно привязан к Docker API, что ограничивает его функциональность в сравнении с Kubernetes.
Возможности настройки и расширения в Docker Swarm ограничены.
Что такое Kubernetes?
Kubernetes – это портативный облачный инфраструктурный инструмент с открытым кодом, изначально разработанный Google для управления своими кластерами. Поскольку он является инструментом оркестрации контейнеров, то он автоматизирует масштабирование, развертывание и управление контейнерными приложениями.
Kubernetes имеет более сложную структуру кластера, чем Docker Swarm.
Kubernetes – это многофункциональная платформа, главным образом потому, что она с выгодой для себя использует активную деятельность мирового сообщества.
Преимущества Kubernetes
Он способен поддерживать большую рабочую нагрузку и управлять ей.
У него большое сообщество разработчиков открытого ПО, поддерживаемого Google.
Поскольку он имеет открытый исходный код, то он предлагает широкую поддержку сообщества и возможность работы с разнообразными сложными сценариями развертывания.
Его предлагают все основные поставщики облачных услуг: Google Cloud Platform, Microsoft Azure, IBM Cloud и AWS.
Он автоматизирован и поддерживает автоматическое масштабирование.
Он многофункционален, имеет встроенный мониторинг и широкий спектр доступных интеграций.
Недостатки Kubernetes
Несмотря на то, что Kubernetes обладает большим набором функций, он также имеет и несколько недостатков:
Процесс обучения Kubernetes достаточно сложный, и для освоения Kubernetes требуются специальные знания.
Процесс установки достаточно сложен, особенно для новичков.
Поскольку сообщество разработчиков открытого ПО работает достаточно продуктивно, Kubernetes требует регулярной установки обновлений для поддержания последней версии технологии без прерывания рабочей нагрузки.
Для простых приложений, которые не требуют постоянного развертывания, Kubernetes слишком сложный.
Kubernetes VS Docker Swarm
Теперь, когда мы узнали все преимущества и недостатки Kubernetes и Docker Swarm, давайте посмотрим, чем же они отличаются друг от друга.
Основное различие этих двух платформ заключается в их сложности. Kubernetes хорошо подходит для сложных приложений, а Docker Swarm разработан для простоты использования, что говорит о том, что его предпочтительнее использовать с простыми приложениями.
Далее приведем подробное описание нескольких различий между Docker Swarm и Kubernetes:
Установка и настройка
Kubernetes можно настроить, но сделать это будет не так просто. Docker Swarm установить и настроить намного легче.
Kubernetes: в зависимости от операционной системы ручная установка может отличаться. Если вы пользуетесь услугами поставщика облачных технологий, то установка не требуется.
Docker Swarm: экземпляры Docker обычно одинаковы для различных операционных систем и поэтому довольно просты в настройке.
Балансировка нагрузки
Docker Swarm предлагает автоматическую балансировку нагрузки, а Kubernetes – нет. Однако в Kubernetes легко интегрировать балансировку нагрузки с помощью сторонних инструментов.
Kubernetes: службы можно обнаружить через одно DNS-имя. Kubernetes обращается к контейнерным приложениям через IP-адрес или HTTP-маршрут.
Docker Swarm: поставляется со встроенными балансировщиками нагрузки.
Мониторинг
Kubernetes: имеет встроенный мониторинг, а также поддержку интеграции со сторонними инструментами мониторинга.
Docker Swarm: нет встроенных механизмов мониторинга. Однако он поддерживает мониторинг через сторонние приложения.
Масштабируемость
Kubernetes: обеспечивает масштабирование в зависимости от трафика. Встроено горизонтальное автомасштабирование. Масштабирование Kubernetes включает в себя создание новых модулей и их планирование для узлов с имеющимися ресурсами.
Docker Swarm: обеспечивает быстрое автоматическое масштабирование экземпляров по запросу. Поскольку Docker Swarm быстрее развертывает контейнеры, то это дает инструменту оркестрации больше времени на реакцию, что позволяет масштабировать по требованию.
Какую платформу все же выбрать?
И Kubernetes, и Docker Swarm служат для конкретного назначения. Какой из них лучше, зависит от ваших текущих потребностей или потребностей вашей организации.
При запуске Docker Swarm – это простое в использовании решение для управления вашими контейнерами. Если вам или вашей компании не нужно управлять сложными рабочими нагрузками, то Docker Swarm – правильный выбор.
Если же ваши приложения имеют более ключевую роль, и вы хотите включить функции мониторинга, безопасности, высокой доступности и гибкости, то Kubernetes – вот ваш выбор.
Подведем итог
Благодаря этой статье мы узнали, что такое Docker Swarm и Kubernetes. Также мы узнали об их плюсах и минусах. Выбор между этими двумя технологиями достаточно субъективен и зависит от желаемых результатов.
Привет! Мы уже рассказывали про операционные системы для устройств Cisco – IOS, IOS-XE, CatOS. В этой статье мы рассмотрим NX-OS и IOS-XR, а также сравним их с традиционной IOS.
На верхнем уровне их можно соотнести так:
Cisco IOS: используется в borderless сетях (то есть это сети, которые позволяют кому угодно, где угодно и с любого устройства подключаться к корпоративной сети). Например, маршрутизатор ISR2 Cisco 3900 Series использует Cisco IOS;
Cisco NX-OS: используется в коммутаторах Cisco Nexus, расположенных в центрах обработки данных. Например, коммутатор Cisco Nexus 7000 работает под управлением Cisco NX-OS;
Cisco IOS-XR: используется на маршрутизаторах провайдеров связи. Например, маршрутизатор Cisco XR 12000 Series использует Cisco IOS-XR.
Cisco IOS
Хотя имя «IOS» появилось позже, операционная система относится к середине 1980-х годов. Cisco IOS была разработана с использованием языка программирования C и имела несколько ограничений, указывающих на то, когда она была разработана. Например, он не поддерживал симметричную многопроцессорную обработку. В результате одна инструкция должна была быть завершена до того, как начнется выполнение другой. Еще одним огромным архитектурным ограничением было использование общего пространства памяти, в результате которого один неправильный процесс мог нанести ущерб другим процессам маршрутизатора.
У некоторых платформ марщрутизаторов были обходные пути. Например модульный маршрутизатор Cisco 7513 – он может быть оснащен модулем универсального интерфейса (VIP), который позволяет отдельным линейным картам запускать собственные экземпляры Cisco IOS. Это обеспечило некоторый уровень балансировки нагрузки и избыточности.
Еще одна версия Cisco IOS - это IOS-XE, которая запускает Cisco IOS в Linux. В качестве примера можно найти Cisco IOS-XE, работающую на маршрутизаторе Cisco ASR 1000 Series. Благодаря набору функций Linux, Cisco IOS-XE добавляет поддержку симметричной многопроцессорности и отдельных пространств памяти. Однако, помимо своих Linux-подходов, Cisco IOS-XE в основном похожа на традиционную Cisco IOS.
Cisco NX-OS
Первоначально имевшая название SAN-OS (где акроним SAN обозначался как Storage Area Network), NX-OS предлагает некоторые обширные архитектурные улучшения по сравнению с традиционными Cisco IOS. Хотя первоначально это была 32-разрядная операционная система, с тех пор она превратилась в 64-разрядную ОС. В отличие от Cisco IOS, NX-OS не использует одно пространство памяти и поддерживает симметричную многопроцессорность. Она также имеет превентивную многозадачность, что позволяет высокоприоритетному процессу получить время процессора перед процессом с более низким приоритетом.
NX-OS построена на ядре Linux, и поддерживает язык Python для создания сценариев на коммутаторах Cisco Nexus. Кроме того, она имеет несколько функций высокой доступности (high availability), и не загружает сразу все ее функции. Вместо этого можно указать, какие функции вы хотите активировать. Устранение ненужных функций освобождает память и процессор для тех функций, которые вам нужны. Однако когда дело доходит до конфигурации, существует много сходства между NX-OS и Cisco IOS.
Cisco IOS-XR
Первоначально разработанная для 64-разрядной работы, IOS-XR предлагает множество улучшений, обнаруженных в NX-OS (например, симметричная многопроцессорность, отдельные пространства памяти и активация только тех сервисов, которые необходимы). Однако, хотя NX-OS построена на ядре Linux, IOS-XR построен на микроядре QNX Neutrino Microkernel.
Функция IOS-XR, которой нет в NX-OS, - это возможность иметь один экземпляр операционной системы, управляющей несколькими шасси. Кроме того, поскольку IOS-XR ориентирована на среды провайдеров, она предлагает поддержку таких интерфейсов, как DWDM и Packet over SONET.
В то время как конфигурация IOS-XR имеет некоторое сходство с традиционной IOS, различия намного заметнее, чем различия в NX-OS. Например, когда вы закончили вводить команды конфигурации, вам необходимо зафиксировать свои изменения, чтобы они вступили в силу и до выхода из режима конфигурации.
Примеры конфигурации
Чтобы проиллюстрировать некоторые основные конфигурации этих трех операционных систем, рассмотрим следующие примеры.
Эти команды были предоставлены маршрутизатору Cisco IOS, коммутатору NX-OS и экземплярам маршрутизатора IOS-XR, работающим в Cisco VIRL. В каждом из следующих примеров показана текущая версия маршрутизатора или коммутатора. Затем мы входим в глобальный режим конфигурации и изменяем имя хоста маршрутизатора или коммутатора, а затем создаем интерфейс Loopback 0, назначая IP-адрес этому интерфейсу, выходя из режима привилегий и выдавая команду show ip interface brief.
При назначении IP-адресов интерфейсам Loopback на устройствах следует заметить, что Cisco IOS требует, чтобы маска подсети была введена в десятичной системе с точками, в то время как NX-OS и IOS-XR поддерживают ввод маски подсети с использованием слеша.
Также нужно обратить внимание, что перед выходом из режима конфигурации необходимо выполнить команду commit на IOS-XR. Кроме того, только когда мы применяем эту команду, применяется наша обновленная конфигурация имени хоста.
IOS:
Router>show version
Cisco IOS Software, C2900 Software (C2900-UNIVERSALK9-M), Version 15.1(4)M4, RELEASE SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2012 by Cisco Systems, Inc.
Compiled Thurs 5-Jan-12 15:41 by pt_team
ROM: System Bootstrap, Version 15.1(4)M4, RELEASE SOFTWARE (fc1)
cisco2911 uptime is 40 seconds
System returned to ROM by power-on
System image file is "flash0:c2900-universalk9-mz.SPA.151-1.M4.bin"
Last reload type: Normal Reload
This product contains cryptographic features and is subject to United
States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.
A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html
If you require further assistance please contact us by sending email to
export@cisco.com.
Cisco CISCO2911/K9 (revision 1.0) with 491520K/32768K bytes of memory.
Processor board ID FTX152400KS
3 Gigabit Ethernet interfaces
DRAM configuration is 64 bits wide with parity disabled.
255K bytes of non-volatile configuration memory.
249856K bytes of ATA System CompactFlash 0 (Read/Write)
License Info:
License UDI:
-------------------------------------------------
Device# PID SN
-------------------------------------------------
*0 CISCO2911/K9 FTX15246R1P
Technology Package License Information for Module:'c2900'
----------------------------------------------------------------
Technology Technology-package Technology-package
Current Type Next reboot
-----------------------------------------------------------------
ipbase ipbasek9 Permanent ipbasek9
security None None None
uc None None None
data None None None
Configuration register is 0x2102
Router>en
Router#conf t
Enter configuration commands, one per line. End with CNTL/Z.
Router(config)#hostname IOS-ROUTER
IOS-ROUTER(config)#interface loopback0
IOS-ROUTER(config-if)#
%LINK-5-CHANGED: Interface Loopback0, changed state to up
%LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback0, changed state to up
IOS-ROUTER(config-if)#ip address 10.1.1.1 255.255.255.255
IOS-ROUTER(config-if)#end
IOS-ROUTER#
%SYS-5-CONFIG_I: Configured from console by console
IOS-ROUTER#show ip int brief
Interface IP-Address OK? Method Status Protocol
GigabitEthernet0/0 unassigned YES unset administratively down down
GigabitEthernet0/1 unassigned YES unset administratively down down
GigabitEthernet0/2 unassigned YES unset administratively down down
Loopback0 10.1.1.1 YES manual up up
Vlan1 unassigned YES unset administratively down down
IOS-ROUTER#
NX-OS:
switch#show version
Cisco Nexus Operating System (NX-OS) Software
TAC support: http://www.cisco.com/tac
Copyright (c) 2002-2010, Cisco Systems, Inc. All rights reserved.
The copyrights to certain works contained herein are owned by
other third parties and are used and distributed under license.
Some parts of this software are covered under the GNU Public
License. A copy of the license is available at
http://www.gnu.org/licenses/gpl.html.
Software
BIOS: version 1.3.0
loader: version N/A
kickstart: version 5.0(2)N2(1) [build 5.0(2)N2(1)]
system: version 5.0(2)N2(1) [build 5.0(2)N2(1)]
power-seq: version v1.2
BIOS compile time: 09/08/09
kickstart image file is: bootflash:/sanity-kickstart
kickstart compile time: 12/6/2010 7:00:00 [12/06/2010 07:35:14]
system image file is: bootflash:/sanity-system
system compile time: 12/6/2010 7:00:00 [12/06/2010 08:56:45]
Hardware
cisco Nexus5010 Chassis ("20x10GE/Supervisor")
Intel(R) Celeron(R) M CPU with 2073416 kB of memory.
Processor Board ID JAF1228BTAS
Device name: BEND-2
bootflash: 1003520 kB
Kernel uptime is 0 day(s), 3 hour(s), 30 minute(s), 45 second(s)
Last reset
Reason: Unknown
System version:
Service:
plugin
Core Plugin, Ethernet Plugin, Fc Plugin
switch# conf t
Enter configuration commands, one per line. End with CNTL/Z.
switch(config)# hostname NEXUS-SWITCH
NEXUS-SWITCH(config)#interface loopback0
NEXUS-SWITCH(config-if)# ip address 10.2.2.2/32
NEXUS-SWITCH(config-if)#end
NEXUS-SWITCH# show ip int brief
IP Interface Status for VRF “default” (1)
Interface IP Address Interface Status
Lo0 10.2.2.2 protocol-up/link-ip/admin-up
NEXUS-SWITCH#
IOS-XR:
RP/0/RP/CPU0:router# show version
Mon May 31 02:14:12.722 DST
Cisco IOS XR Software, Version 4.1.0[Default]
Copyright (c) 2010 by Cisco Systems, Inc.
ROM: System Bootstrap, Version 2.100(20100129:213223) [CRS-1 ROMMON],
router uptime is 1 week, 6 days, 4 hours, 22 minutes
System image file is "bootflash:disk0/hfr-os-mbi-4.1.0/mbihfr-rp.vm"
cisco CRS-8/S (7457) processor with 4194304K bytes of memory.
7457 processor at 1197Mhz, Revision 1.2
2 Management Ethernet
8 GigabitEthernet
12 SONET/SDH
12 Packet over SONET/SDH
1 WANPHY controller(s)
1 TenGigE
1019k bytes of non-volatile configuration memory.
38079M bytes of hard disk.
3607592k bytes of disk0: (Sector size 512 bytes).
3607592k bytes of disk1: (Sector size 512 bytes).
RP/0/RP/CPU0:router#conf t
RP/0/RP/CPU0: router(config)#hostname IOS-XR-ROUTER
RP/0/RP/CPU0: router(config)#interface loopback0
RP/0/RP/CPU0: router(config-if)#ip address 10.3.3.3/32
RP/0/RP/CPU0: router(config-if)#commit
RP/0/RP/CPU0: IOS-XR-ROUTER (config-if)#end
RP/0/RP/CPU0: IOS-XR-ROUTER (config)#show ip int brirf
Interface IP-Address Status Protocol Vrf-Name
Loopback0 10.3.3.3 Up Up default
MgmtEth0/0/CPU0/0 unassigned Shutdown Down default
GigabitEthernet0/0/0/0 unassigned Shutdown Down default
RP/0/RP/CPU0: IOS-XR-ROUTER#
REST API – один из самых распространенных типов доступных веб-сервисов, но проектировать их сложно. Они позволяют разным клиентам, включая браузер, настольные приложения, мобильные приложения и практически любое устройство с подключением к Интернету, взаимодействовать с сервером. Именно поэтому очень важно правильно проектировать REST API, чтобы в будущем не было проблем.
Создание API с нуля может оказать непосильной задачей из-за большого количества вещей, которые необходимо учесть – от базовой безопасности до использования правильных методов HTTP, реализации аутентификации, определения того, какие запросы и ответы среди многих других принимаются и возвращаются. В этой статье я очень постарался сжать материал в 15 пунктов с важными рекомендациями, которые позволят создать хороший API. Все рекомендации никак не зависят от языка, поэтому потенциально применимы к любой платформе или технологии.
1. Обязательно используйте имена существительные в названиях путях к конечным точкам
Вам всегда следует использовать имена существительные, которые обозначают объект, который вы извлекаете или которым вы манипулируете. В качестве имени пути всегда предпочтительнее использовать множественное число. Избегайте использования глаголов в названиях путях к конечным точкам, потому что наш метод HTTP-запроса уже является глаголом и по сути не добавляет никакой новой информации.
Действие должно быть произведено с помощью методов HTTP-запроса. Наиболее распространенными являются методы GET, POST, PATCH, PUT и DELETE.
GET извлекает ресурсы
POST отправляет новые данные на сервер
PUT/PATCH модифицируют уже существующие данные
DELETE удаляет данные
Глаголы сопоставляются с функциями CRUD (Create, read, update и delete).
Помня об этих принципах, мы должны создавать маршруты типа GET /books для получения списка книг, а не GET /get-books или GET /book. Аналогично, POST /books - для добавления новой книги, PUT /books/:id - для модификации полных данных книги с заданным идентификатором (id), а PATCH /books/:id обновляет частичные изменения в книге. И наконец, DELETE /books/:id предназначен для удаления существующей книги в заданным идентификатором.
2. JSON как основной формат отправки и получения данных
Несколько лет назад прием и ответы на запросы API выполнялись в основном в XML. Но сейчас «стандартным» форматом для отправки и получения данных API в большинстве приложений стал JSON. Поэтому наш второй пункт рекомендует убедиться, что конечные точки возвращают формат данных JSON в качестве ответа, а также при приеме информации через полезную нагрузку HTTP-сообщений.
Несмотря на то, что FormData хорошо подходит для отправки данных от клиента, особенно если нам нужно отправлять файлы, они не очень подходят для текста и чисел. Нам не нужны FormData для их передачи, так как в большинстве фреймворков можно передавать JSON непосредственно на стороне клиента. При получении данных от клиента нам необходимо убедиться, что клиент правильно интерпретирует данные JSON, и для этого при выполнении запроса в заголовке ответа Content-Type должен быть установлен на application/json.
Стоит еще раз упомянуть исключение, когда мы пытаемся отправлять и получать файлы между клиентом и сервером. В этом конкретном случае нам необходимо обрабатывать файл ответа и отправлять FormData с клиента на сервер.
3. Используйте коды состояний HTTP
Коды состояний HTTP всегда полезно использовать для того, чтобы указать на выполнение или невыполнение запроса. Не используйте слишком много кодов состояний и всегда используйте одни и те же коды для одних и тех же результатов в API. Вот некоторые примеры:
200 – общее выполнение
201 – успешное создание
400 – неверные запросы от клиента, такие как неверные параметры
401 – несанкционированные запросы
403 – отсутствие прав доступа к ресурсам
404 – отсутствуют ресурсы
429 – слишком много запросов
5хх – внутренние ошибки (их следует избегать насколько это возможно)
В зависимости от ситуаций их может быть и больше, но ограничение количества кодов состояний помогает клиенту использовать более предсказуемый API.
4. Возвращайте стандартизированные сообщения
Помимо использования кодов состояния HTTP, которые указывают на результат запроса, всегда используйте стандартизированные ответы для аналогичных конечных точек. Пользователи могут всегда рассчитывать на одинаковую структуру и действовать соответственно. Это также относится к статусу, указывающему на выполнение запроса, и сообщениях об ошибках. В случае выборки коллекций придерживайтесь определенного формата, независимо от того, включает ли тело ответа массив данных, подобный этому:
[
{
bookId: 1,
name: "The Republic"
},
{
bookId: 2,
name: "Animal Farm"
}
]
или вот такой комбинированный ответ:
{
"data": [
{
"bookId": 1,
"name": "The Republic"
},
{
"bookId": 2,
"name": "Animal Farm"
}
],
"totalDocs": 200,
"nextPageId": 3
}
Здесь рекомендация заключается в том, чтобы быть последовательным независимо от того, какой подход вы выберете для этого. Аналогичное поведение должно быть реализовано при извлечении объекта, а также при создании и модификации ресурсов, которым обычно рекомендуется возвращать последний экземпляр объекта.
// Ответ после успешного вызова POST /books
{
"bookId": 3,
"name": "Brave New World"
}
Хоть это и никак не навредит, но все же излишнем будет включать универсальное сообщение, например, «Книга успешно создана», так как это уже следует из кода состояния HTTP.
И последнее, но не менее важное: при наличии стандартного формата ответа коды ошибок также важны (и даже более важные). Это сообщение должно включать информацию, которую клиент может использовать для представления ошибок конечному пользователю, а соответственно, это должно быть не общее предупреждение, такое как «то-то пошло не так», которого следует избегать, насколько это возможно. Вот пример:
{
"code": "book/not_found",
"message": "A book with the ID 6 could not be found"
}
Опять же, нет необходимости включать код состояния в содержимое ответа, но полезно определить набор кодов ошибок, таких как book/not_found, чтобы пользователь мог сопоставить их с разными строками и создать свое собственное сообщение об ошибке для конечного пользователя. В частности, для сред разработки или промежуточных сред может показаться правильным также включить стек ошибок в ответ с целью помочь в отладке ошибок. Но не включайте те, что находятся в промышленной эксплуатации, так как это создаст угрозу безопасности, раскрывая незапланированную информацию.
5. Используйте разбиение на страницы, фильтрацию и сортировку при выборе коллекций записей
Как только будет создана конечная точка, которая возвращает список элементов, необходимо будет установить разбиение на страницы. Обычно коллекции со временем растут, поэтому важно всегда следить за тем, чтобы возвращалось ограниченное и контролируемое количество элементов. Справедливо будет позволить пользователям API выбирать, сколько объектов получить, но всегда полезно заранее определить число и установить для него максимум. Основная причина, почему нужно это сделать, заключается в том, что для возврата огромного массива данных потребуется очень много времени и большая пропускная способность.
Для реализации нумерации страниц есть два хорошо известных способа: skip/limit или keyset. Первый вариант обеспечивает более удобный для пользователя способ извлечения данных, но обычно он менее эффективен, так как базы данных сканируют множество документов для извлечения нужных записей. Мне больше нравится второй вариант. Разделения на страницы с помощью keyset получает идентификатор (id) в качестве ссылки для «вырезания» коллекции или таблицы с условием без сканирования записей.
Также API должны предоставлять фильтры и возможности сортировки, которые упрощают способы получения данных. Частью решения повышения производительности являются индексные базы данных, которые позволяют максимизировать производительность при помощи шаблонов доступа, которые применяются с фильтрами и параметрами сортировки.
При проектировании API эти свойства разбиения на страницы, фильтрации и сортировки определяются как параметры запроса в URL-адресе. Например, если вы хотим получить информацию о первых 10 книгах, принадлежащих к категории «роман», то наша конечная точка будет выглядеть вот так:
GET /books?limit=10&category=romance
6. PATCH вместо PUT
Маловероятно, что необходимо будет сразу полностью обновить всю запись, обычно есть конфиденциальные или полные записи, которые следует уберечь от манипуляций пользователя. Именно поэтому для выполнения частичных обновлений ресурса следует использовать PATCH, а вот PUT полностью меняет существующий ресурс. Они оба должны использовать тело запроса для передачи информации, подлежащей модификации. Разница лишь в том, что для PATCH это поля, а для запроса PUT – полный объект. Тем не менее, стоит отметить, что ничто не мешает нам использовать PUT для частичной модификации, нет никаких «ограничений на передачу по сети», которые бы это подтверждали. Это просто факт, которого стоит придерживаться.
7. Предоставьте более подробные ответы
Шаблоны доступа являются ключевыми при создании доступных ресурсов API и возвращаемых данных. Когда система растет, то и свойства записи также растут, но не всегда все эти свойства нужны клиентам для работы. Именно в таких ситуациях становится полезным предоставление возможности возвращать сокращенные или полные ответы для одной и той же конечной точки. Если пользователю нужны только некоторые поля, то упрощенный ответ помогает снизить расход трафика и потенциально сложность получения других вычисляемых полей.
Простой способ реализовать – предоставить дополнительный параметр запроса, чтобы включить или отключить предоставление более подробного ответа.
GET /books/:id
{
"bookId": 1,
"name": "The Republic"
}GET /books/:id?extended=true
{
"bookId": 1,
"name": "The Republic"
"tags": ["philosophy", "history", "Greece"],
"author": {
"id": 1,
"name": "Plato"
}
}
8. Обязанность конечной точки
Принцип единственной обязанности фокусируется на концепции удержания функции, метода или класса на одной обязанности, которую они выполняют хорошо. Мы можем сказать, что это наш API - хороший API, если он выполняет одну конкретную вещь и никогда не меняется. Это помогает пользователям лучше понять наш API и сделать его более предсказуемым, что облегчит общую интеграцию. Лучше всего расширить список доступных конечных точек, а не создавать очень сложные конечные точки, которые пытаются решить множество задач одновременно.
9. Предоставьте полную документацию по API
Пользователи вашего API должны понимать, как использовать доступные конечные точки и чего ожидать. Это возможно только при наличии хорошей и подробной документации. Обратите внимание на следующие аспекты, чтобы ваша документация была полной.
Доступные конечные точки с описанием их назначения
Права доступа, необходимые для выполнения конечной точки
Примеры вызовов и ответов
Сообщения о предполагаемых ошибках
Немаловажным является постоянное обновление документации после внесения изменений и дополнений в систему. Лучший способ для этого – сделать документацию по API неотъемлемой частью разработки. Двумя хорошо известными инструментами в данном вопросе являются Swagger и Postman – они доступны для большинства сред разработки API.
10. Используйте SSL для обеспечения безопасности и настройте CORS
Безопасность – еще одно очень важной свойство, которым должен обладать наш API. Настройка SSL путем установки действительного сертификата на сервер обеспечит безопасную связь с пользователями и предотвратит некоторые виды потенциальных атак.
CORS (Cross-origin resource sharing – Обмен ресурсами с запросом происхождения) – это функция безопасности браузера, которая ограничивает HTTP-запросы из различных источников, которые инициируются сценариями, запущенными в браузере. Если ресурсы вашего REST API получают непростые HTTP-запросы из разных источников, то вам нужно включить поддержку CORS для того, чтобы пользователи работали соответствующим образом.
Протокол CORS требует, чтобы браузер отправил предварительный запрос на сервер и дождался утверждения (или запрос учетных данных) с сервера перед отправкой фактического запроса. Запрос предварительной проверки отображается в API как HTTP-запрос, использующий метод OPTIONS (среди других заголовков). Значит, для поддержки CORS в ресурсе REST API необходимо реализовать метод OPTIONS, который будет отвечать на предварительный запрос, по крайней мере, со следующими заголовками ответа, предусмотренными стандартом Fetch:
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Allow-Origin
Какие значения назначать этим ключам, зависит от того, настолько открытым и гибким должен быть наш API. Мы можем назначить определённые методы и известные источники или использовать специальные символы, чтобы иметь открытые ограничения CORS.
11. Управление версиями API
В процессе разработки конечные точки начинают меняться и перестраиваться. Но мы должны, насколько это возможно, избегать внезапного изменения конечных точек для пользователя. Рекомендуется рассматривать API как ресурс с обратной совместимость, в котором новые и обновленные конечные точки должны быть доступны, но не должны влиять на предыдущие стандарты.
Вот где управление версиями API приходит на помощь – когда клиенты должны иметь возможность выбирать, к какой версии подключаться. Есть несколько способов описать управление версиями API:
Добавление нового заголовка x-version=v2
Наличие параметра запроса ?apiVersion=2
Версия как часть URL: /v2/books/:id
12. Кэшируйте данные для повышения производительности
Чтобы повысить производительность нашего API, полезно следить за данными, которые редко меняются и к которым часто обращаются. Для таких данных мы можем рассмотреть возможность использования базы данных в памяти или кэш-памяти, которая избавит от доступа к основной базе данных. Главная проблема здесь заключается в том, что данные могут устареть, поэтому следует решить вопрос с внедрением последней версии.
Использование кэшированных данных будет полезным для пользователей для загрузки конфигураций и каталогов информации, которые не предназначены для постоянного изменения в течение долгого времени. При использовании кэширования не забудьте включить Cache-Control в заголовки. Это поможет пользователям эффективно использовать систему кэширования.
13. Используйте даты в формате UTC
Сложно представить системы, которые в какой-то момент перестает работать из-за дат. На уровне данных важно быть логичным в том, как даты отображаются на клиентских приложениях. ISO 8601 – это международный стандартный формат данных для даты и времени. Данные должны быть в формате Z или UTC, для которых пользователи могут могли бы выбрать часовой пояс в случае, если такая дата должны отображаться при любых условиях. Вот пример того, как должны выглядеть даты:
{
"createdAt": "2022-03-08T19:15:08Z"
}
14. Конечная точка проверки работоспособности
Может произойти ситуация, когда наш API перестанет работать, и для его запуска потребуется время. При таких обстоятельствах клиенты хотят знать, что службы недоступны, и быть в курсе ситуации. Для этого предоставьте конечную точку (например, GET /health), которая бы определяла работоспособность API. Эта конечная точка может вызываться и другими приложениями, такими как балансировщики нагрузки. Можно продвинуться еще дальне и сообщать о периодах технического обслуживания или работоспособности частей API.
15. Разрешите аутентификацию по ключу API
Аутентификация с помощью ключей API даст возможность сторонним приложениям легко создавать интеграцию с нашим API. Эти ключи API следует передавать с помощью пользовательского заголовка HTTP (например, Api-Key или X-Api-Key). Ключи должны иметь дату окончания срока действия, и должна быть возможность их отозвать с целью признания недействительными по соображениям безопасности.