Что такое API и почему он есть у любого проекта?

Если вы изучали вакансии на джунов-разработчиков, в 90% из них вы видели в требованиях либо знание REST API, либо SOAP API, либо оба. API – это основа практически любого проекта, без тщательно продуманных еще на стадии планирования интерфейсов разработка либо существенно затянется (и съест много денег), либо вообще застопорится. Ниже – о том, почему API всем так нужен и какой минимум вам нужно знать, чтобы утверждать: «Владею REST API».

Определение API + зачем он нужен

Определение

Аббревиатура API расшифровывается как «Application Programming Interface», в переводе – интерфейс программирования приложения. Как это и бывает с аббревиатурами в IT, из расшифровки ничего не понятно, поэтому постараемся дать более человеческое определение: API – это четкий набор действий, которые вы можете совершать с приложением. Если вы уже учили ООП, то вы знаете, что такое «инкапсуляция»; так вот, API – это буквально реализация инкапсуляции. Если вы ООП не учили, то для объяснения того, зачем API нужен, понадобится подводка.

Самая большая проблема в IT

Итак, самая большая проблема в IT – сделать так, чтобы несколько человек могли слаженно работать над одной задачей. В «бородатые нулевые», когда IT еще был крайне молодой сферой и большинство сервисов/приложений писались «на коленке», каждый разработчик старался сделать что-то свое, идеальное по мнению его внутреннего перфекционизма. На словах звучит романтично, на деле же такой подход мог угробить весь проект: внезапно могло оказаться, что разработчик, ответственный за критическую часть приложения, реализовал эту самую критическую часть каким-то очень запутанным алгоритмом, а затем уволился; или решение разработчика конфликтует с остальным функционалом приложения; или два разработчика независимо друг от друга написали решение одной и той же проблемы, и теперь выясняют, чье именно решение должно использоваться в проекте.

По мере появления в IT больших денег такие проблемы становились все более и более дорогими для бизнеса, и бизнес нашел ряд решений для того, чтобы синхронизировать работу внутри команды разработки. 3 самых известных инструмента для решения проблем синхронизации – это:

1. Agile. Несколько видов управления разработкой проекта. Самый популярный – Scrum – предполагает работу по спринтам: выделяем месяц, расписываем задачи на этот месяц, распределяем задачи между разработчиками. Основа Scrum – ежедневные созвоны (дэйли), на которых каждый участник команды может рассказать, какую работу он вчера выполнил и какие проблемы у него возникли. Проблемы стараются решить сразу – поэтому если кто-то «уперся в стену» (словил блокер) из-за действий другого разработчика, то он потеряет день разработки, что не так страшно.
2. Git. Вообще, речь идет о системах контроля версий, но самая популярная и доминирующая среди них – Git. Git позволяет разработчикам работать в своих «ветках», поэтому каждый разработчик может быть уверен, что его разрабатываемый функционал не затрет кто-то другой. Когда функция в ветке полностью реализована – эту функцию переносят в основной билд (мастер), если в процессе возникают какие-то конфликты – их решают на месте.
3. API. Интерфейсы, позволяющие разработчикам оперировать конкретными (описанными в документации) командами и получать конкретный (описанный в документации) результат.

Как API решает проблемы синхронизации разработчиков?

Выше мы уже упоминали инкапсуляцию – один из принципов ООП. Инкапсуляция – это когда мы скрываем внутренности нашего приложения/сервиса, оставляя открытым только интерфейс, то есть конкретные способы взаимодействия с модулем.

Например, мы разработали калькулятор, который принимает на вход 2 числа и операцию, после чего отдает результат применения операции к этим числам («число 1» «операция» «число 2», «5» «+» «3»). Наш калькулятор версии 1.0 реализован довольно просто: есть класс, в котором описаны 2 целочисленные (int) переменные; у класса есть метод, который принимает 2 переменные и символ, после чего с помощью if’а перебирает символ на соответствие одному из 4-х основных (+, -, *, /), производит вычисление и возвращает результат. Если мы не пользуемся инкапсуляцией, то мы объявляем переменные как public, и любой другой кусок кода в нашей программе может напрямую записать любое значение в объект класса. И это – большая проблема, потому что любой сторонний сервис может влезть в наш объект и что-то где-то перезаписать – при неудачном стечении обстоятельств может получиться так, что «5+3» выдаст нам «-10», потому что пока наш объект производил свои вычисления, кто-то влез в объект и поменял переменные. Проблемой будет и изменение нашего собственного кода – как только мы решим для версии 1.1 переименовать переменные с «a» и «b» на «value1» и «value2», у всех, кто ссылался на «a» и «b» в своем коде, тут же все сломается, и к нам придут разбираться недовольные разработчики.

Итак, как нам решить проблему? К нашему калькулятору нужно применить инкапсуляцию – скрыть все внутренности разработки и создать интерфейс. Внутренности скрываются очень просто: делаем наши переменные private. Если кто-то на этот момент уже ссылался на них – он получит ошибку, но это – не ваша проблема. Далее мы разбиваем метод, которому передавали числа, на отдельные операции: calc.add(); calc.divide() и так далее. Эти методы мы делаем public – теперь сторонние разработчики могут ими пользоваться. Можно было, к слову, оставить единый метод, но есть золотое правило: один метод выполняет одну задачу, старайтесь этого правила придерживаться. Все, мы инкапсулировали наш калькулятор: сторонние приложения могут использовать только те методы, которые мы указали, «движок» скрыт. Если мы решим что-то поменять в алгоритме вычислений – никто ничего не узнает, при этом же ни у кого ничего не сломается.

Можно было бы сказать, что наши методы calc.add(), calc.divide() и остальные как раз и являются API – мы ведь получили программный интерфейс, который является четким набором действий. Да, у нас уже почти есть API, но ему кое-чего не хватает, и в статьях про API об этой важной детали упоминают редко. Итак, нашему API не хватает документации. Технически у публичных API может и не быть документации, но если вы хотите, чтобы ваше приложение (и его интерфейс) кого-то заинтересовали – нужно написать хотя бы минимальный гайд, который рассказывает:

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

Если вы создали приложение, которым могут пользоваться все – API имеет смысл выложить в публичный доступ; если у приложения есть какие-то ограничения (оно, например, платное) – можно предоставлять доступ и к самому API, и к документации по запросу (для таких API обычно выпускают токены доступа, которые получают покупатели).

Итак, как API позволяет разработчикам более эффективно взаимодействовать друг с другом? 3 пункта:

1. Инкапсуляция, проводимая в рамках разработки API, скрывает внутреннюю реализацию функционала. Это заставляет других разработчиков пользоваться вашим приложением только «разрешенными» путями, что исключает ошибки, связанные с прямым доступом ко «внутренностям» приложения.
2. API декларирует конкретный набор функций приложения. Сторонний разработчик, пользующийся вашим приложением, четко знает, что и в каком формате он может получить – не нужно гадать, может данный модуль сделать определенную работу или не может.
3. Хороший API имеет достаточно полную документацию. Если в процессе работы с вашим API сторонний разработчик получит ошибку от функции – он сможет пойти и посмотреть, что эта ошибка значит. И вас дергать не будет, и сам лишнего времени не потратит.

Какие бывают API

Технически под определение API подходит практически любой интерфейс, к которому можно обратиться, поэтому, например, графический интерфейс вашего компьютера или смартфона – это тоже API, к которому вы обращаетесь своими пальцами (а графический интерфейс, в свою очередь, обращается к ядру операционной системы). Но обычно при обсуждении API имеют в виду либо Web API, либо внутренний API. Внутренний API – это интерфейс, который используется строго внутри проекта: например, фронтенд обращается к бэкенду с запросом внутри сайта (наш пример API выше – тоже внутренний API). А вот Web API – это практически любой интерфейс (обычно – от стороннего разработчика), к которому можно обратиться через интернет. Видов Web API – много:

• REST API. Самый популярный на данный момент, о нем расскажем ниже.
• SOAP. Был популярен до того, как на рынок пришел REST. В SOAP используется язык разметки XML, который позволяет составлять сложные и высокоструктурированные запросы. Кроме того, SOAP позволяет отправлять запросы по различным протоколам прикладного уровня – FTP, например (в то время как REST использует только протоколы HTTP и HTTPs). Увы, все эти преимущества – не преимущества: сложность и громоздкость запросов делает этот тип Web API медленным, а для передачи SOAP-пакетов не через HTTP(s) нужна особая настройка, с которой нужно серьезно заморочиться. Именно из-за всего этого REST уверенно вытесняет SOAP с рынка. Хорошо знать SOAP нужно только тем, кто поддерживает легаси-проекты.
• GraphQL. API, нередко использующаяся в проектах с открытым исходным кодом. Основное преимущество – вы можете запросить только те данные, которые вам необходимы, что существенно уменьшает количество передаваемой информации и увеличивает скорость работы сервера. Если вы только знакомитесь с IT – почитать про GraphQL ради интереса стоит, но учить этот API большого смысла нет, лучше взяться за REST.
• RPC. Когда вы пользуетесь любым из вышеперечисленных API – вы составляете запрос к серверу по строгому протоколу доступа, и сервер отправляет вам ответ. RPC упрощает эту схему: вам не нужно обращаться с запросом по форме стандартного протокола, вы как-бы напрямую обращаетесь к функции, находящейся где-то на другом сервере. Это существенно ускоряет работу, но в RPC есть куча своих нюансов – в основном они связаны с реализацией и интеграцией (там нужно учить отдельный язык запросов). Когда освоитесь с REST – есть смысл присмотреться к RPC, самые распространенные реализации – gRPC, tRPC.

REST API

REST API – самый распространенный Web API на сторонних сайтах, поэтому если вы хотите стать разработчиком – его нужно знать обязательно. Детальный разбор REST API выходит за рамки этого материала, но если вкратце:

1. REST – это архитектура, а не протокол, поэтому вы имеете определенную гибкость в реализации.
2. REST в 99.9% случаев реализован поверх протокола HTTP, поэтому методы REST обычно построены на методах HTTP (так называемый CRUD: Create, Read, Update, Delete).
3. «RESTful» – это когда приложение полностью соответствует архитектуре REST.
4. REST позволяет соединять что угодно с чем угодно: сервер с мобильным устройством, микросервисы с монолитами и так далее. Все это работает довольно быстро (быстрее – только RPC).
5. REST как архитектура строится на 6 принципах, 5 – обязательных, 1 – опциональный.

Что касается архитектурных принципов REST:

1. Клиент-серверная модель. Есть сервер, который обрабатывает запросы, и есть клиент, который эти запросы посылает. Запрос – «единица» общения.
2. Stateless. Сервер не хранит никаких данных о предыдущих запросах клиента, то есть в каждом новом запросе клиент должен давать всю необходимую информацию для полного ответа снова.
3. Кэширование. Если какой-то запрос повторяется часто, и ответ на него всегда один и тот же – нужно завести отдельный маленький сервер, который будет хранить такие «типовые» ответы и выдавать их по требования.
4. Единый интерфейс. Интерфейс не должен зависеть от приложения, то есть интерфейс любого приложения должен быть создан по единым для всех правилам. Этот свод правил для REST называется
5. Многоуровневость. У сервера должны быть прокси, серверы для кэширования, серверы для проверки безопасности и так далее. Вся эта реализация должна быть скрыта от клиента.
6. Код по требованию (опционально). Сервер может отправить в ответ на запрос кусок кода, который нужно исполнить – обычно это JavaScript. Принцип опционален, потому что не всем приложениям нужно, чтобы на стороне клиента что-то выполнялось. Но если есть возможность – лучше переложить задачу на клиента.

Где искать API?

В Гугле. Без шуток, первое место, в котором вам стоит проверить нужный вам API – поисковик. API большинства крупных сервисов без проблем гуглятся, например:

• Amazon.
• Apple.
• Telegram.

Если найти нужный API не удалось – ищите более глубоко, в техподдержке сервиса и на Реддите. Посмотрите прайсинг сервиса – возможно, API доступен только тем, кто его оплатил. Ну а если вы и здесь ничего не найдете – возможно, нужного вам API просто нет, так тоже бывает.

FAQ

Что такое API?

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

Какие проблемы решает API?

API решает проблемы синхронизации работы программистов на уровне приложений. Достигается это за счет трех преимуществ API:

1. Внутренности приложения скрыты за интерфейсом, поэтому ваши изменения в логике работы приложения не затронут других разработчиков (если вы все не сломаете сами, конечно).
2. Интерфейс четко прописан, поэтому разработчики заранее знают, чего ожидать от вашего приложения.
3. У хорошего API есть документация, и если что-то пойдет не так – разработчики не будут дергать вас с вопросами, а просто найдут все ответы в документации.

Какой API учить?

Начните с принципов REST API, когда хорошо с ним разберетесь – можете «пощупать» SOAP и RPC для разнообразия.

Как написать свой API?

Для начала вам нужно написать приложение, но сразу вас предупреждаем – API лучше планировать еще на стадии разработки архитектуры приложения, тогда вся разработка пойдет легче. Заложите в приложение принципы REST – клиент-серверную модель, stateless, единый интерфейс. Если приложение – достаточно объемное, можете задуматься над кэшированием и многоуровневостью (если делаете пет-проект для резюме – обязательно закладывайте и то, и то, чтобы получить RESTful). Написали приложение, реализовали API – напишите документацию. Протестируйте API на работоспособность – готово.