По вашему запросу ничего не найдено :(
Убедитесь, что запрос написан правильно, или посмотрите другие
наши статьи:
Если Вы не раз сталкивались с большими списками доступа и/или входящими в них object-группами, то наверняка уже задавались вопросом, существует ли инструмент, позволяющий определить, пропустит ли access-лист некий заданный трафик и вообще, какие строки имеют к этому отношение.
Конечно, такие инструменты существуют и полностью или частично решают перечисленные задачи. Однако, эти инструменты как правило являются частью функционала больших "комбайнов" управления сетью, 90% функционала которых Вас не интересует.
Чтобы продолжить, необходимо скачать утилиту ACL check
Безусловно, никто не запрещает использовать регулярные выражения для поиска определённых строк списка доступа прямо в консоли сетевого устройства. Но данный метод предоставит очень поверхностный результат. Например, он не отобразит доступ хоста, попадающего в сетевую маску или порт, попадающий под диапазон. Тем более, таким образом нельзя отобразить все существующие доступы между двумя заданными узлами/сетями. Знающий сетевой администратор осведомлён о безрезультативности метода простого парсинга access-листа в таких ситуациях.
Данная небольшая утилита создана именно для этого - найти строки access-листа, разрешающие или запрещающие определённый сетевой трафик. И даже более - выявить все строки, имеющие отношение к доступам между интересующими узлами или сетями.
Идея использования проста: Вы задаёте критерий, а программа находит строки access-листа, которые ему удовлетворяют. При этом, сам критерий выглядит как строка access-листа, но без использования оператора "permit" или "deny".
Если регулярно добавлять сетевые правила в access-лист без должной проверки их существования, то списки доступа могут содержать большое количество избыточных правил. Чтобы навести порядок в таких access-листах, в данной программе реализован функционал анализа списков доступа на избыточность. Вы можете выявить ненужные строки и освободить ресурсы оборудования.
Для анализа ACL с object-группами программе необходимо указать состав object-групп. Вывод ACL будет предоставлен в развёрнутом виде.
У нас есть нужные для изучения листов доступа статьи:
Стандартные листы контроля доступа (ACL)
Расширенные листы контроля доступа (Extended ACL)
Интерфейс программы
Поле ввода access-листа
Поле ввода object-групп
Кнопка распознавания access-листа
Поле вывода access-листа в детальном виде
Однострочное поле ввода условия
Многострочный список ввода условий
Кнопка прямой проверки
Кнопка обратной проверки
Поле результата проверки
Шкала позиционирования поля детальных результатов (11) по отношению ко всему ACL
Поле просмотра детальных результатов проверки
Кнопка анализа ACL на конфликты и избыточность
Кнопка сортировки строк ACL по различным критериям
Маркер текущего активного условия в многострочном списке (6)
Шкала сокращённого обозначения результатов проверки условий многострочного списка
Переключатель типа маски для различного типа сетевого устройства
Переключатель алгоритма проверки адресов источника и назначения
Активация режима игнорирования строк ACL с ICMP протоколом в режиме частичного совпадения адресов
Меню выбора вариантов CLI команд в составе с именем ACL
Вывод object-групп, используемых в распознанном ACL
Вывод списка известных программе именованных протоколов, а также типов и кодов ICMP
Поле вывода ошибок, возникающих в процессе распознавания ACL
Основные шаги
Исходный access-list необходимо скопировать в поле 1. Если он содержит object-группы, то их состав необходимо скопировать в поле 2. ACL и object-группы можно копировать как с конфигурации устройства (“show running-config”, “show startup-config”), так и по прямым командам “show access-lists”, “show object”.
Ниже приведён пример результата команды “show running-config”, допустимого для использования в поле 1:
ip access-list extended ACL
permit icmp host 172.16.0.6 host 172.21.0.6
permit ip host 172.16.0.6 host 172.21.0.1
permit tcp host 192.168.8.15 range 1024 65534 host 192.168.66.47
permit tcp 192.168.8.0 0.0.0.255 eq 22 1521 3389 addrgroup ADMIN_BSD
permit tcp host 192.168.8.12 eq 1521 192.168.83.20 0.0.0.1
Тот же access-list по команде “show access-lists”:
Extended IP access list ACL
10 permit icmp host 172.16.0.6 host 172.21.0.6
20 permit ip host 172.16.0.6 host 172.21.0.1 (32 matches)
30 permit tcp host 192.168.8.15 range 1024 65534 host 192.168.66.47
40 permit tcp 192.168.8.0 0.0.0.255 eq 22 1521 3389 addrgroup ADMIN_BSD (1 match)
50 permit tcp host 192.168.8.12 eq 1521 192.168.83.20 0.0.0.1
Пример результата команды “show running-config”, допустимого для использования в поле 2:
object-group ip address ADMIN_BSD
host-info 10.237.92.131
host-info 10.22.145.132
host-info 10.22.145.136
host-info 10.22.145.141
Содержимое вывода команды “show object-group”:
IP address object group ADMIN_BSD
host 10.237.92.131
host 10.22.145.132
host 10.22.145.136
host 10.22.145.141
Также допустимы и другие форматы object-групп. Пример допустимого фрагмента команды “show running-config”:
object-group network Servers
host 10.15.12.5
host 10.15.5.11
host 10.15.4.2
host 10.15.7.34
object-group service Ports1
tcp-udp eq domain
tcp-udp eq 88
udp range 3268 3269
tcp gt 49151
Пример того же фрагмента команды “show object-group”:
Network object group Servers
host 10.15.12.5
host 10.15.5.11
host 10.15.4.2
host 10.15.7.34
Service object group Ports1
tcp-udp eq domain
tcp-udp eq 88
udp range 3268 3269
tcp gt 49151
После копирования ACL и object-групп необходимо нажать кнопку 3. В результате access-list будет распознан и отображён в развёрнутом виде (в случае использования object-групп) в поле 4. Если на этапе распознавания возникли ошибки, то они будут отображены в поле 22.
Если номер строки конечного access-листа дополнен ‘0’, это означает, что данная строка получена из object-группы.
Если access-лист скопирован вместе с его заголовком, то активируется кнопка 19, позволяющая использовать команды конфигурирования, содержащие имя access-листа.
После распознавания ACL необходимо в поле 5 ввести условие для поиска интересуемого нас доступа и нажать кнопку 7. Результат поиска доступа отобразится в поле 9. В случае наличия доступа более детальная информация появится в поле 11. Вызов контекстного меню “Показать результат” по правой кнопке мыши на поле 11 позволит отобразить строки ACL, удовлетворяющие условию поиска.
Проверка существования доступа между заданными узлами по определённому порту
Предположим, нас интересует существование доступа с хоста 192.168.1.2 по порту TCP 1521 на сервер 192.168.2.2 в следующем списке доступа:
ip access-list extended ACL
10 permit tcp 192.168.1.0 0.0.0.255 192.168.2.0 0.0.0.255 range 1521 1522
20 permit tcp host 192.168.1.2 any
30 permit tcp host 192.168.1.3 any eq 1521
Копируем access-лист в поле 1 и нажимаем кнопку 3. В поле 5 вводим следующее условие:
tcp host 192.168.1.2 gt 1023 host 192.168.2.2 eq 1521
Нажимаем кнопку 7 или клавишу “Enter”. В поле 9 отобразится результат:
Разрешено в строке 1: 10 permit tcp 192.168.1.0 0.0.0.255 192.168.2.0 0.0.0.255 range 1521 1522
Имеются ещё совпадения
Здесь значение “1:” является результатом сквозной нумерации всех строк конечного (распознанного) ACL, а “10” – номер строки в исходном ACL. Надпись “Имеются ещё совпадения” означает, что в ACL присутствуют и другие строки, в которых теоретически может сработать наше условие. Результаты совпадения правил можно просмотреть в поле 11. Если на этом поле вызвать контекстное меню (правой кнопкой мыши) и выбрать пункт “Показать результат”, то появится дополнительное окно с выборкой сработавших строк ACL.
Определение узлов заданной сети, к которым имеется доступ по определённому порту
Рассмотрим ситуацию, когда требуется выяснить, к каким серверам сети 192.168.2.0 /24 открыт доступ по SSH (TCP 22). Список доступа следующий:
ip access-list extended ACL
10 permit tcp 192.168.1.0 0.0.0.255 192.168.2.0 0.0.0.255 range 1521 1522
20 permit tcp any 192.168.2.0 0.0.0.3 eq 22 3389
30 permit tcp host 192.168.1.3 host 192.168.2.254
40 permit tcp host 192.168.1.10 any
Копируем access-лист в поле 1 и нажимаем кнопку 3. Ставим переключатель 17 в положение “частичное по src и dst”. Алгоритм будет учитывать строки ACL, в которых IP-адреса источника и назначения полностью или частично попадают в диапазон адресов, указанный в условии.
В поле 5 вводим следующее условие:
tcp any gt 1023 any eq 22
Нажимаем кнопку 7 или клавишу “Enter”. В поле 9 отобразится результат
Блок
Результаты совпадения правил можно просмотреть в поле 11. Если на этом поле вызвать контекстное меню (правой кнопкой мыши) и выбрать пункт “Показать результат”, то появится дополнительное окно с выборкой сработавших строк ACL. Символ “?” в этом окне означает частичное совпадение по адресам.
Определение доступов, открытых между определёнными узлами
Выясним, какие доступы открыты от узла 192.168.1.10 к узлу 192.168.2.254 в следующем ACL:
ip access-list extended ACL
10 permit tcp 192.168.1.0 0.0.0.255 192.168.2.0 0.0.0.255 range 1521 1522
20 permit tcp any 192.168.2.0 0.0.0.3 eq 22 3389
30 permit tcp host 192.168.1.3 host 192.168.2.254
40 permit tcp host 192.168.1.10 any
Копируем access-лист в поле 1 и нажимаем кнопку 3. Ставим переключатель 17 в положение “частичное по src и dst”. В поле 5 вводим следующее условие:
ip host 192.168.1.10 host 192.168.2.254
Метод состоит в том, что заданное условие рассматривается как access-лист, а каждая строка исходного ACL как отдельное условие. Другими словами, условие и ACL меняются ролями. Кнопка (8), решающая эту задачу, называется “Обратная проверка”. Нажимаем кнопку 8 или комбинацию “Ctrl-Enter”. В поле 9 отобразится результат:
Блок
Результаты совпадения правил можно просмотреть в поле 11. Если на этом поле вызвать контекстное меню (правой кнопкой мыши) и выбрать пункт “Показать результат”, то появится дополнительное окно с выборкой сработавших строк ACL. Символ “?” в этом окне означает частичное совпадение по адресам.
Важным требованием при такой проверке является необходимость установки переключателя 17 в среднее положение.
Многострочный список условий (поле 6)
Список условий (6) предназначен для ввода нескольких условий и последовательной их проверки. Для ввода каждого следующего условия (новой строки) предусмотрена комбинация “Shift-Enter”. Для проверки условия из списка необходимо установить на него курсор и нажать кнопку 7 (Enter) или 8 (Ctrl-Enter). На шкале 15 напротив строки запрошенного условия отобразится соответствующий символ результата. Он сохранится до изменения условия в этой строке списка.
Сортировка (кнопка 13)
Распознанный access-list, выведенный в развёрнутом виде в поле 4, можно упорядочить по различным критериям и их комбинации. При нажатии на кнопку сортировки (13) открывается дополнительное окно.
1-7 – Кнопки включения элементов в цепь сортировки
8 – Отображение исходных номеров строк
9 – Режим группирования результатов сортировки
Каждый следующий критерий в цепочке выбирается соответствующей кнопкой. Рассмотрим следующий список доступа:
1 permit udp 192.168.8.0 0.0.0.255 host 192.168.38.24 eq syslog
2 permit tcp 192.168.8.0 0.0.0.255 host 192.168.38.23 eq 1514
3 permit tcp 192.168.8.0 0.0.0.255 host 192.168.38.24 eq 1514
4 permit tcp 192.168.8.0 0.0.0.255 host 192.168.38.23 eq 4041
5 permit tcp 192.168.8.0 0.0.0.255 host 192.168.12.26
6 permit ip 192.168.8.0 0.0.0.255 192.168.41.0 0.0.0.255
7 permit ip 192.168.8.0 0.0.0.255 host 192.168.41.31
Чтобы упорядочить эти строки сначала по IP адресу назначения, а затем по протоколу, необходимо нажать последовательно кнопки 5 и 1:
Цифры в круглых скобках на соответствующих кнопках указывают позицию элемента в цепочке сортировки. При отключении элемента из цепочки также исключаются все элементы с номерами выше отключенного.
Анализ на конфликты и избыточность (кнопка 12)
Кнопка “Анализ” (12) становится активной после распознания access-листа. Её нажатие запускает процесс анализа строк access-листа на конфликты и избыточность. Конфликтующей является строка access-листа, которая никогда не сработает из-за вышестоящего правила противоположного значения (“deny” после “permit” или наоборот).
К примеру, загрузим следующий ACL:
10 permit icmp any any
20 permit tcp host 10.15.2.11 eq 1521 host 10.15.1.10
30 deny tcp 10.15.2.0 0.0.0.255 10.15.0.0 0.0.31.255
40 permit udp 10.15.2.0 0.0.0.255 host 10.19.9.232
50 permit udp 10.15.2.0 0.0.0.255 host 10.19.9.120 eq syslog
60 permit tcp host 10.15.2.11 eq 1521 host 10.15.7.11
Распознаем его (кнопка 3) и нажмём кнопку “Анализ” (12). Программа предупредит нас о имеющихся конфликтах:
Кнопка “Да” откроет окно с результатами анализа, включающими только конфликты:
Если нажать кнопку ‘Нет’, то откроется окно, включающее как конфликтующие, так и избыточные правила. Рассмотрим следующий access-list:
10 permit icmp any any
20 permit tcp host 192.168.1.10 host 192.168.2.20 eq 22
30 permit tcp host 192.168.1.10 host 192.168.2.20
40 permit ip 192.168.1.0 0.0.0.255 192.168.2.0 0.0.0.255
Анализ такого ACL отобразит следующие результаты:
Здесь жирным шрифтом выделены строки, если имеются другие правила, попадающие под их действие. Остальные строки (обычный шрифт) являются производными правилами.
Установив курсор на определённой строке, удерживая нажатой клавишу “Ctrl”, получим детальную информацию в нижней части окна:
Поле результатов
Поле детализации выбранного правила
Иерархический вид детализации
В данном случае правило 2 является производным от правила 3. В свою очередь, правило 3 входит в правило 4. Визуально уровень такой вложенности можно определить по отступам строки вправо или выбрать иерархический вид (3). При иерархическом виде производные правила будут выведены ниже строк, в которые они входят. Можно выделить диапазон интересуемых строк в поле 1 и вызвать контекстное меню правой кнопкой мыши, в котором выбрать варианты удаления избыточных строк.
Следует учитывать намеренное чередование операторов “permit” и “deny” в одном ACL для его упрощения. В таких случаях следует анализировать ACL частями. Например, до и после операторов “deny”. Либо анализировать полностью, но дополнительно обращать внимание на порядок следования конфликтующих строк в ACL и не удалять такие производные строки из исходного ACL.
Опции запуска программы
Предусмотрены следующие опции запуска exe-файла:
/h, /?, /help – вызов справки параметров запуска
/l (rus) – выбор языка
/nm – включение режима “netmask”
/pm (and,or) – выбор режима совпадения адресов
/skipicmp – включение режима “игнорировать ICMP при частичном совпадении”.
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). Ключи должны иметь дату окончания срока действия, и должна быть возможность их отозвать с целью признания недействительными по соображениям безопасности.
Компания Microsoft изменила браузерный движок родного Edge, и теперь он работает на движке Chromium. Скачать новую версию Edge Canary можно c официального сайта для различных ОС, в т.ч. macOS и Linux. В последней версии браузере имеется скрытая функция - отправлять вкладку в другой профиль. Новый функционал позволяет пересылать вкладки между профилями, которые могут использованы для определенных задач (учеба, развлечение, работа) или принадлежать членам семьи.
Переключаться между профилями удобно, например, имея профиль Учеба, Работа, Развлечения, можно иметь возможность меньше отвлекаться, т.к. не будет открыто "лишних" вкладок. Или добавить профили членам семьи, где каждый будет иметь свою историю просмотров, избранное, параметры и расширения.
При открытии, Edge, к которому подключена запись Microsoft, он в фоновом режиме синхронизирует историю просмотров, избранное, сохраненные пароли. И при входе на другом компьютере, с этой же учетной записью - все эти данные появляются. А тот профиль, который локальный и не синхронизируется, будет находиться только на данном устройстве.
Edge работает с одним профилем "По умолчанию". При желании, или как было написано выше, можно создать дополнительные профили для каждого члена семьи. Все данные Edge Canary хранятся в папке %LocalAppData%MicrosoftEdge SxSUser Data.
На данный момент функционал перемещения вкладок находится в стадии тестирования, поэтому такую возможность необходимо сначала активировать. Это можно сделать с помощью скрытых настроек.
Включить возможность переноса вкладки в другой профиль в Microsoft Edge Canary. Запустить Microsoft Edge Canary.
В адресной строке ввести edge://flags/#edge-move-tabs-to-profile-window и нажать Enter.
Изменить значение параметра "Enable move tabs to a different profile window" с Default на Enabled.
Перезапустить браузер.
Функция переноса вкладок активирована.
Добавление нового профиля
Можно щелкнуть на иконку профиля и выбрать "Добавить профиль" и затем подтвердить его добавление.
Либо в адресной строке набрать edge://settings/profiles и нажать Enter. Перейдем в Параметры Профилей, нажмем на "+ Добавить профиль". И после подтверждения профиль будет создан.
Открыть Microsoft Edge Canary.
Открыть сайт или перейти на вкладку, которую хотите перенести в другой профиль.
Щелкнуть по этой вкладке правой кнопкой мыши.
Выбрать "Переместить вкладку в окно профиля ...".