Одно из самых востребованных IT-решений: простыми словами об API13.03.2024 00:00

Любой современной IT-компании так или иначе приходится работать с данными: они используются как в оптимизации показателей самой компании, так и в предоставлении услуг потребителям. Задача часто осложняется необходимостью управления и передачи больших объемов данных, поэтому организовать работу с ними помогают API. Об API сегодня и поговорим в данной статье: разберемся, что они из себя представляют, зачем нужны и почему так востребованы.

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

Давайте познакомимся. Меня зовут Александр, занимаюсь веб-разработкой, в частности — разработкой API для стартапа NFCKEY. В прошлом имел подобный опыт при создании платформы хедхантинга, направленной на достаточно узкую целевую аудиторию и партнерские отношения. Учусь на ошибках и люблю разбираться в тонкостях своей работы, в особенности обусловленной спецификой стартапа.

По плану разберем следующее:

Что такое API и где используется?

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

API (от англ. application programming interface — «интерфейс программирования приложения») — программный интерфейс, описывающий способы взаимодействия одной программы с другими. Его внутренняя логика скрыта, но в центре внимания находится именно конечный результат взаимодействия и правила, по которым оно организуется. Продолжим пример с пользовательским интерфейсом: вы нажимаете на кнопку, сообщая программе о своих намерениях, а программа использует API, чтобы запросить нужные данные.

Говоря о примерах применения, одними из наиболее востребованных и популярных в нашем мире являются API картографических сервисов (Google Maps, Яндекс Карты). Благодаря ним любой желающий может воспользоваться их функционалом: создать интерактивную карту и показывать, например, расположение офиса или магазина.
К тому же вы наверняка пользовались вариантом входа в какое-либо приложение или сайт при помощи учетной записи Google, Apple, VK. Это является возможным как раз благодаря API. Прогнозы погоды, информация об авиабилетах, банковские платежи — все это примеры использования, которые показывают широту спектра решаемых задач.

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

Почему проектам необходим именно API?

Веб-интерфейсы API в наше время стали повсеместно используемой технологией, выступающей в роли своеобразной магистрали. Многие компании в значительной степени полагаются на подобную инфраструктуру для обслуживания клиентов. Так, например, любой сайт из топ-100 интернет-рейтинга Alexa использует API и/или предоставляет свои собственные API, что является достаточно четким показателем огромного масштаба и влияния веб-интерфейсов в целом.

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

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

Проект по созданию системы умных замков, которым я занимаюсь в данный момент, является IoT стартапом, для которого задача разработки собственного API является одной из ключевых. В ходе статьи я буду обсуждать и брать в пример некоторые специфические для него решения. Хотел бы отметить, что одна из главных проблем подобных проектов заключается в сложной взаимосвязи между аппаратными и программными компонентами. В нашем же случае все части, включая физический замок, его встроенное программное обеспечение и мобильное приложение нуждаются в надежном программном решении, которое позволит обеспечить бесперебойную связь и согласованность данных. Эту ответственность на себя может взять как раз серверная часть с веб-интерфейсом программирования приложений (Web API).

Как устроен API?

Web API состоит из нескольких конечных точек для определенной системы сообщений «запрос-ответ». Стоит уточнить, что существуют различные типы API, но одними из наиболее распространенных являются REST API, использующие формат JSON (JavaScript Object Notation) для обмена данными. Про остальные типы можете узнать больше в данной статье.
Здесь мы можем рассмотреть распространенный вариант клиент-серверной архитектуры:

Сервер — удаленный узел, который хранит и обрабатывает ресурсы. Здесь мы храним необходимые данные, а также устанавливаем то, как они обрабатываются и предоставляются клиентам.

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

Каждой функциональности в системе соответствует определенная конечная точка, что обеспечивает четкую и модульную организацию функций. Одной из практик является использование ресурсо-ориентированного подхода, при котором такие объекты, как пользователи, журналы и другие объекты, рассматриваются как ресурсы (или коллекции ресурсов) с уникальными конечными точками для их получения/создания/обновления/удаления. JSON в свою очередь служит форматом обмена данными и представления упомянутых ресурсов, обеспечивающим легкую и человекочитаемую структуру. К тому же для сериализации и десериализации данных (преобразования в/из) JSON существует множество средств, способных помочь разработчикам.

Таким образом, клиент знает, как обращаться к серверу, и запрограммирован обрабатывать ожидаемый результат, а сервер знает, как отвечать клиенту, и запрограммирован обрабатывать входные данные и формировать ответы. Условно, если нам будет необходимо изменить внутреннюю бизнес-логику, например, числа в системе ограничений, то мы сможем изменить их в серверной части без необходимости обновлять клиентское приложение. Кроме того, подход с использованием API позволяет беспрепятственно подключить новых клиентов. В нашем проекте одним из таких клиентов мы можем рассмотреть веб-сайт, дополняющий возможности мобильного приложения. Личный кабинет, почему бы и нет?

При помощи чего разрабатывают API?

Перейдем к технологиям, используемым для разработки API. Бесспорно ценную информацию, с которой можно начинать идти вперед, могут предоставить исследования, связанные с миром разработки ПО. Среди наиболее значимых можно выделить Stack Overflow Developer Survey и JetBrains: Экосистема разработки. Подобная информация позволяет оценить тенденции мира разработки ПО и определить исходный перечень кандидатов:

Технологий действительно много и все они имеют свои особенности, преимущества и недостатки, поэтому разумным решением становится проведение сравнительного анализа с учетом потребностей проекта.

Как провести сравнительный анализ технологий для разработки API?

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

1. Для оценки определяются критерии, которые взвешиваются на основе их важности, что позволяет учитывать большее значение некоторых факторов в контексте требований и задач проекта.

2. В системе оценок применяется числовая шкала от 1 до 5, где каждое значение представляет собой качественную оценку (1 — «плохо», 5 — «отлично»). При оценке допускается использовать дробные числа, придающие детализированный характер для учета нюансов различий в показателях и в достаточной мере позволяющие отобразить индивидуальные достоинства и недостатки каждого кандидата.

3. Каждый выбранный фреймворк (технология) оценивается по заранее установленным критериям с присвоением баллов по шкале. Для повышения обоснованности и надежности сравнительного анализа может проводиться обзор тематических исследований, отраслевых тенденций и эмпирических данных.

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

5. Признавая достаточно субъективный характер некоторых критериев, при выставлении баллов учитывается авторское суждение, особенно в тех областях, где качественные оценки по своей сути субъективны. Каждая оценка может быть сопровождена комментарием, в котором формулируется обоснование выставленной оценки, что позволит обеспечить прозрачность и лучшую интерпретируемость результатов.

Определенно стоит признать, что методология имеет свои недостатки и к тому же может показаться слишком ресурсозатратной в современных реалиях, где необходимость скорейшим образом разработать MVP просто не оставляет времени на подобные вещи.

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

Итоговым вариантом для нас стал PHP-фреймворк Laravel. Признаваемый некоторыми разработчиками «умирающим» языком, PHP по-прежнему активно используется и развивается в стремительном темпе. Соответствующие веб-фреймворки свободно применяются для разработки проектов и по-прежнему занимают нишу в различных опросах и инфографиках. Laravel — самый популярный PHP-фреймворк последних лет, который привлекает внимание своей архитектурой, реализующей множество шаблонов проектирования и предоставляющей ряд удобных для разработчиков функций. Разработчик Laravel, Тэйлор Отвел, выпустил первую версию в 2011 году, а в настоящее время фреймворк продолжает активно развиваться и обновляться вслед за его языком программирования.

Не буду слишком расхваливать данный фреймворк и вставать на защиту как его слабых сторон, так и языка PHP в целом, однако сочетание простоты и гибкости, выразительный синтаксис, разнообразие функционала и масштаб экосистемы способны представить Laravel в качестве варианта, не только удовлетворяющего требованиям многих проектов, но и адаптируемого к будущим расширениям.

Путь разработки и возникающие сложности

Предлагаю уделить немного внимания техническим подробностям: процессу разработки и возникающим проблемам. Отмечу, что описание основано на работе конкретно с Laravel и может не передать специфику работы с другими технологиями и фреймворками. Также отмечу, что некоторые детали намеренно опускаются с целью продемонстрировать общие этапы, а не продвинутый гайд »How to…». Тем не менее, все равно жду комментариев про вынесение логики из контроллеров в сервисы и репозитории!

Я стараюсь делать все стандартизировано и обдуманно, поэтому путь от проектирования ER-диаграммы к релизу конечной точки API выглядит примерно следующим образом:

1. Создаются миграции для базы данных, описываются классы моделей и связанные с ними отношения. Отношения, в частности с Eloquent ORM, являются очень удобным инструментом, который помогает сэкономить десятки лишних строк кода и потраченные на них часы времени. На днях передо мной встала задача группировки некоторых данных и представления их коллекции в виде желаемой JSON-схемы. Я решил ее за 2 часа, прошерстив StackOverflow и использовав метод «проб и ошибок». На следующий же день ко мне пришло озарение и, описав новое отношение буквально в 5 строчек кода, я удалил и переписал весь вчерашний код. Получилось достигнуть того же результата, но быстрее, аккуратнее и без костылей.

2. Описываются классы ресурсов и коллекций опираясь на то, какой результат должен возвращаться в JSON. Здесь же включается предварительная логика того, кому какие данные могут быть видны.

3. Продумывается структура данных, на основе которых будет работать вся внутренняя логика, и создаются Request-классы. В них можно удобно сгруппировать всю логику валидации и предварительной обработки данных, оставляя классам-контроллерам «свежий воздух».

4. Определяются маршруты (конечные точки) и методы, по которым они будут доступны. Здесь важно думать о той же безопасности и применять посредники API. Тот же посредник Laravel Sanctum позволяет ограничить доступность маршрутов для неавторизованных пользователей и учесть полномочия токенов.

5. Переход к основной части — разработке логики классов-контроллеров. Здесь ведется работа с ранее созданными моделями и отношениями для получения результата в соответствии с задуманной бизнес-логикой.

6. Тестируются изменения на локальном сервере, в чем могут помочь Laravel Sail и ПО по типу Postman. По необходимости дорабатываются Request-, Resource-классы и вносятся коррективы в маршруты и логику контроллеров. Каждый контроллер уникален, поэтому в каких-то местах дополнительно приходится создавать события (например, чтобы отправить уведомление), где-то предоставлять возможности фильтрации по query-параметрам, например, через Pipeline.

Возвращаясь к бизнес-логике и контроллерам, могу поделиться несколькими базовыми, но полезными вещами, к которым я пришел через какое-то время. Кому-то они могут показаться абсурдно смешными, но новичкам в Laravel могут оказаться полезными.

Во-первых, очень практичным ходом является вынесение каких-либо идентификаторов, значений или сообщений в константы. Это позволяет не исправлять код в нескольких местах.

json($user, 200);
}

 $code,
		'message' => $message
	];
	
	if (count($resource)) {
		$result = array_merge($result, ['data' => $resource['data']]);
	}
	
	return response()->json($result, $code);
}

// Определение метода контроллера ...
public function show(User $user): JsonResponse
{
	$userResource = (new UserResource($user))->response()->getData(true);
    
	return $this->wrapResponse(Response::HTTP_OK, 'Success', $userResource);
}