[Перевод] Глава 6: Проектирование API17.03.2025 20:46

Структура мини-курса Мини-курс API-интерфейсы для самых маленьких.

1. Введение в API

2. Протоколы API

3. Типы и форматы API

4. Проверка подлинности API, часть 1: Основные и ключевые

5. Проверка подлинности API, часть 2: OAuth

6. Проектирование API

7. Взаимодействие с API в режиме реального времени

8. Реализация API

Глава 6 знаменует собой поворотный момент в нашем приключении с API. Мы закончили рассматривать основы и теперь готовы увидеть, как предыдущие концепции объединяются, чтобы сформировать API. В этой главе мы обсудим компоненты API, проектируя его.

Структура главы 6

1. REST против SOAP

2. Что такое проектирование API?

3. Как работает REST API

4. Шаг 1: Выбор ресурсов

5. Шаг 2: Назначение URL-адресов

6. Шаг 3: Определение действий клиента

7. Шаг 4: Определение данных для обмена

8. Объединение ресурсов

9. Поиск данных

10. Краткое содержание главы 6

REST против SOAP

При обсуждении API вы можете услышать разговоры о »мыле» (soap) и »отдыхе» (rest) и задаться вопросом, работают ли разработчики программного обеспечения или планируют день СПА. Правда в том, что это названия двух наиболее распространенных архитектур для веб-API. SOAP (ранее аббревиатура) — это основанный на XML дизайн, который имеет стандартизированные структуры для запросов и ответов.

SOAP когда-то обозначал Simple Object Access Protocol. Первоначально он использовался для очень специфического типа доступа к API. Поскольку разработчики нашли способы применять его в большем количестве ситуаций, название перестало подходить, поэтому в версии SOAP 1.2 аббревиатура была удалена.

Что такое проектирование API?

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

Хорошо спроектированный API имеет несколько ключевых преимуществ:

• Предоставляет разработчикам понятный, интуитивно понятный интерфейс для доступа к ресурсам

• Обеспечивает эффективную, надежную и предсказуемую интеграцию с низким риском ошибок кодирования

• Способствует взаимодействию между разнообразными системами, программным обеспечением и приложениями

Итак, что именно входит в хорошо спроектированные API?

Как и все сложные процессы, все начинается с организации.

Задумайтесь на мгновение о вашем Google Drive. Вы один из тех людей, которые сваливают все в одну папку, или один из тех, кто тщательно упорядочивает свои фотографии, документы и таблицы в логическую иерархию четко обозначенных папок?

Компании уделяют аналогичное внимание организации при создании своих API. Как мы упоминали в Главе 1, цель API — сделать так, чтобы компьютерам было легко работать с данными компании. С учетом простоты использования одна компания может решить иметь единый URL для всех данных и сделать его доступным для поиска (вроде как иметь одну папку для всех ваших фотографий). Другая может решить дать каждому фрагменту данных свой собственный URL, организованный в иерархию (например, иметь папки и подпапки, сортирующие фотографии по дате, местоположению или событию). Каждая компания выбирает наилучший способ структурирования своего API для своей конкретной ситуации, руководствуясь существующими передовыми отраслевыми практиками.

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

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

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

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

Таблица, сравнивающая стили проектирования API: SOAP и REST.

Ключевые отличия:

1. Формат данных:

   • SOAP использует только XML.

   • REST поддерживает JSON, XML и другие форматы.

2. Протокол передачи:

   • SOAP может работать поверх HTTP, SMTP, TCP и других.

   • REST использует только HTTP/HTTPS.

3. Сложность:

   • SOAP сложнее из-за строгой структуры и стандартов.

   • REST проще и гибче.

4. Безопасность:

   • SOAP имеет встроенные механизмы безопасности (WS-Security).

   • REST требует дополнительных решений (HTTPS, OAuth, JWT).

5. Использование:

   • SOAP подходит для корпоративных систем с высокой безопасностью.

   • REST идеален для веб-API и мобильных приложений.

Когда использовать?

• SOAP:

  • Высокие требования к безопасности.

  • Сложные транзакции (например, банковские системы).

  • Интеграция с legacy-системами.

• REST:

  • Веб-API и мобильные приложения.

  • Быстрая разработка и простота.

  • Высокая производительность и масштабируемость.

Как работает REST API

В Главе 2 мы немного говорили о ресурсах. Вспомним, что ресурсы — это существительные API (клиенты и пиццы). Это те вещи, с которыми мы хотим, чтобы мир мог взаимодействовать через наш API.

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

 Чтобы клиент мог поговорить с нами о пицце, нам нужно сделать несколько вещей:

1. Решить, какие ресурсы должны быть доступны.

2. Назначить URL-адреса этим ресурсам.

3. Решить, какие действия клиенту должно быть разрешено выполнять на этих ресурсах.

4. Выяснить, какие фрагменты данных требуются для каждого действия и в каком формате они должны быть.

Шаг 1: Выбор ресурсов

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

Шаг 2: Назначение URL-адресов

Следующий шаг — назначение URL-адресов ресурсу. Существует множество возможностей, но, к счастью, соглашения REST дают некоторые указания. В типичном REST API ресурсу будет назначено два шаблона URL.

• Первый — это множественное число имени ресурса, например /orders.

• Второй — это множественное число имени ресурса плюс уникальный идентификатор для указания одного ресурса, например /orders/, где  — уникальный идентификатор заказа.

Эти два шаблона URL составляют первые конечные точки, которые будет поддерживать наш API. Они называются конечными точками просто потому, что идут в конце URL-адреса, например http://example.com/.

Шаг 3: Определение действий клиента

Теперь, когда мы выбрали наш ресурс и назначили ему URL-адреса, нам нужно решить, какие действия может выполнять клиент. Следуя соглашениям REST, мы говорим, что конечная точка множественного числа (/orders) предназначена для перечисления существующих заказов и создания новых. Конечная точка множественного числа с уникальным идентификатором (/orders/) предназначена для извлечения, обновления или отмены определенного заказа. Клиент сообщает серверу, какое действие выполнить, передавая соответствующий HTTP-глагол (verb) (GET, POST, PUT или DELETE) в запросе.

Шаг 4: Определение данных для обмена

После того, как действия для наших конечных точек заказа были конкретизированы, последним шагом будет решить, какими данными необходимо обмениваться между клиентом и сервером. Заимствуя из нашего примера с пиццерией в Главе 3, мы можем сказать, что заказу нужны корочка и начинка. Нам также нужно выбрать формат данных, который клиент и сервер могут использовать для передачи этой информации туда и обратно. XML и JSON — оба хорошие варианты, но для удобства чтения мы выберем JSON.

На этом этапе вы должны похлопать себя по спине; мы разработали функциональный API! Вот как может выглядеть взаимодействие между клиентом и сервером с использованием этого API:

Объединение ресурсов

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

Как и в случае с заказами, нашему ресурсу клиента нужны некоторые конечные точки. Согласно соглашению, /customers и /customers/ хорошо подходят. Мы пропустим подробности, но предположим, что мы решили, какие действия имеют смысл для каждой конечной точки и какие данные представляют клиента. Предположив, что мы делаем все это, мы приходим к интересному вопросу: как мы связываем заказы с клиентами?

Практикующие REST разделились во мнении о том, как решить проблему связывания ресурсов. Некоторые говорят, что иерархия должна продолжать расти, предоставляя конечные точки вроде /customers/5/orders для всех заказов клиента № 5 и /customers/5/orders/3 для третьего заказа клиента № 5. Другие утверждают, что нужно сохранять все плоским, включая связанные детали в данные для ресурса. В рамках этой парадигмы создание заказа требует отправки поля customer_id с деталями заказа. Оба решения используются API REST в реальной жизни, поэтому стоит знать о каждом из них.

Поиск данных

По мере роста объема данных в системе конечные точки, которые перечисляют все записи, становятся непрактичными. Представьте, что в нашей пиццерии было три миллиона выполненных заказов, и вы хотите узнать, в скольких из них в качестве начинки была пепперони. Отправка запроса GET на /orders и получение всех трех миллионов заказов не принесет особой пользы. К счастью, REST имеет отличный способ поиска по данным.

URL-адреса имеют еще один компонент, о котором мы еще не упоминали: строку запроса. Запрос означает поиск, а строка означает текст. Строка запроса — это фрагмент текста, который идет в конец URL-адреса для передачи данных в API. Например, все, что находится после вопросительного знака, является строкой запроса в http://example.com/orders? key=value.

REST API используют строку запроса для определения деталей поиска. Эти детали называются параметрами запроса. API определяет, какие параметры он будет принимать, и необходимо использовать точные названия этих параметров. Наш API пиццерии может позволить клиенту искать заказы по топпингу, используя этот URL: http://example.com/orders? topping=pepperoni. Клиент может включить несколько параметров запроса, перечислив их один за другим, разделив их амперсандом (»&»). Например: http://example.com/orders? topping=pepperoni&crust=thin.

 Другое использование строки запроса — ограничение объема данных, возвращаемых в каждом запросе. Часто API разделяют результаты на наборы (например, 100 или 500 записей) и возвращают один набор за раз. Этот процесс разделения данных известен как разбиение на страницы (pagination) (аналогично разбиению слов на страницы в книгах). Чтобы позволить клиенту просматривать все данные, API будет поддерживать параметры запроса, которые позволяют клиенту указывать, какую страницу данных он хочет. В нашем API пиццерии мы можем поддерживать разбиение на страницы, позволяя клиенту указывать два параметра: страницу и размер. Если клиент делает запрос типа GET /orders? page=2&size=200, мы знаем, что он хочет вторую страницу результатов с 200 результатами на странице, поэтому заказы 201–400.

Краткое изложение главы 6

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

Ключевые термины, которые мы узнали:

• SOAP: Архитектура API, известная стандартизированными форматами сообщений

• REST: Архитектура API, которая сосредоточена на управлении ресурсами

• Ресурс (Resource): Термин API для бизнес-существительного, например, клиент или заказ

• Конечная точка (Endpoint): URL, который составляет часть API. В REST каждый ресурс получает свои собственные конечные точки

• Строка запроса (Query string): Часть URL, которая используется для передачи данных на сервер

• Параметры запроса (Query parameters): Пара ключ-значение, найденная в строке запроса (topping=cheese)

• Пагинация (Pagination): Процесс разделения результатов на управляемые фрагменты

Следующая

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