public api что это

Что такое REST API?

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

Чем полезен API?

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

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

API бывают приватными, публичными.

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

Большинство крупных сайтов, (как vk, telegram, twitter) имеют открытый API, который позволяет разработчикам писать программы, ботов, взаимодействующих с данными этих компаний, из своих скриптов. И это взаимодействие, зачастую, предусматривает не только возможность получения, но, так же, и добавления данных (создание постов в группе vk, отправка пользователю запроса в друзья, сообщения и т.д.).

Пользуюсь каждый день, а ты?

А что, если я скажу, что с API вы сталкиваетесь каждый день по несколько раз, вы поверите?
Большинство приложений, которыми вы пользуетесь ежедневно, как раз и используют такой интерфейс.

Но, помимо приложений, подобные реализации применяет множество WEB-сайтов. Которые делают запрос на собственные сервера, для получения данных, и, используя JavaScript, интерактивно обрабатывают полученный результат, и, вместо полной перезагрузки страницы, динамически заменяют только определённый участок html-разметки.

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

Subscribe to Блог php программиста: статьи по PHP, JavaScript, MySql

Get the latest posts delivered right to your inbox

Источник

Что такое API? Простое объяснение для начинающих

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

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

Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). Большинство крупных компаний на определённом этапе разрабатывают API для клиентов или для внутреннего использования. Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина».

Всемирная паутина и удалённые серверы

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

При введении в адресную строку браузера www.facebook.com на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу.

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

API как способ обслуживания клиентов

Многие компании предлагают API как готовый продукт. Например, Weather Underground продаёт доступ к своему API для получения метеорологических данных.

Сценарий использования: на сайте небольшой компании есть форма для записи клиентов на приём. Компания хочет встроить в него Google Календарь, чтобы дать клиентам возможность автоматически создавать событие и вносить детали о предстоящей встрече.

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

В качестве альтернативы браузер может сделать запрос к API сервера Google, минуя сервер компании.

Чем API Google Календаря отличается от API любого другого удалённого сервера в сети?

Технически, разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON.

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

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

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

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

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

Такие запросы часто можно отправлять через браузер. Так как передача данных по протоколу HTTP происходит в текстовом виде, браузер всегда сможет отобразить ответ. Например, через браузер можно напрямую обратиться к API GitHub (https://api.github.com/users/petrgazarov), причём без маркера доступа, и получить вот такой ответ в формате JSON:

Браузер отлично отображает JSON-ответ, который вполне можно вставлять в код. Из такого текста достаточно просто извлечь данные, чтобы использовать их по своему усмотрению.

Онлайн-курсы, чтобы разобраться с API

Ещё несколько примеров API

Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:

Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.

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

Источник

Как сделать Public API, которым будут пользоваться

Во фронтенде практически безраздельно правит OpenSource, а с недавних пор набирает популярность компонентный подход. Вроде бы всё чудесно. Небольшим компаниям компонентный подход помогает переиспользовать код, а крупным компаниям выравнивать UX во всей линейке продуктов, сервисов и прочего. И вот мы все такие замечательные крутые разработчики пилим свои фреймворки, библиотеки и виджеты, радостно полагая, что если они решают наши задачи, то решают и проблемы окружающего мира. Мы выкладываем их в паблик, ожидая благодарных пользователей, звезд на GitHub, скачиваний на NPM-е. Но почему-то одни библиотеки взлетают, а другие остаются незамеченными и позабытыми.

Почему же так происходит. Наверняка бывало, что когда вы искали какую-нибудь библиотеку с необходимой функциональностью или тот же NPM-ный пакет, находили что-то такое:

По сути просто кусок кода. Безо всякого объяснения, что это такое, что оно делает, как этим пользоваться. Если это NPM-ный пакет, то, наверно, можно залезть к нему в кишочки, понять, как он работает, и пользоваться на свой страх и риск. Но если это сервис, то уже ничего не поделаешь — не будешь ведь перебором выяснять, какие у него есть методы и какие данные они ожидают на вход.

Что же мы ожидаем увидеть, когда находим какой-нибудь публичный API? Наверно, что-то такое:

Это NPM от Babel. Здесь рассказывается, что это такое, что оно делает и как этим пользоваться. То есть когда мы выкладываем что-то в публичный доступ, мы должны приложить документацию. Иначе это просто бессмысленно.

Документация

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

По сути это реклама, в которой нам рассказывают какую задачу решает этот API, чем он круче конкурентов, почему вы обязательно должны его использовать, даже если вам это не нужно и всё в таком духе. А уже с этой лендинговой страницы есть ссылки на документацию, в которой обычно есть разделы Getting Started и API Reference.

Getting Started — это раздел для пользователей, которые впервые видят ваш API. В этом разделе описано где скачать, как собрать, как запустить и тому подобное. Также здесь принято описывать, как использовать различные функции продукта. Например, мы в APS, в Getting Started берем маленькое приложение и пошагово добавляем в него различную функциональность, доводя до полноценного боевого решения по которому уже можно делать какие-то свои приложения.

API Reference же предназначен для продвинутых пользователей, которые знают, как пользоваться вашим API и просто хотят уточнить название какого-то свойства или параметры какого-то метода.

Может показаться, что документация это сложно и дорого, потому что её нужно поддерживать в актуальном состоянии, но это, к счастью, немножко не так. Я надеюсь, что вы все себя любите и пишете код с комментариями. Скорее всего, вы описываете свои модули и методы в формате JSDoc, ну просто потому, что это стандарт де-факто в индустрии. А если вы используете React, то у вас есть data-props. Существует много утилит, умеющих собрать JSDoc по вашему коду и выдать JSON-словари, которые можно отображать различными вьюверами так как вам удобно, то есть с сортировкой, поиском, подсветкой, разбиением на категории и всем остальным. С TypeScript говорят тоже все хорошо.

В любой документации должны быть примеры. И очень важно следить за тем, чтобы они работали. Ничто так не портит впечатление о проекте, как сразу же неработающие примеры из документации. Удивительно, но это случается не так редко, как можно было бы подумать.

Песочница

Хорошо, у нас есть примеры, нам кажется что мы помогли людям. Но обычно люди хотят сами с этим поиграться, поэкспериментировать, то есть хотят сами понять, можно ли из этих примеров сделать то, что решает их задачи. Причем они хотят делать это быстро, просто, ничего не скачивая и не устанавливая. И это тоже решаемая задача, ведь мы JavaScript-разработчики, мы практически всё можем запустить в браузере, и у нас давным давно есть наши замечательные песочницы: codepen, jsfiddle, jsbin. Вы можете собрать свой небольшой сниппет с использованием вашего API и добавить в документацию ссылку по которой люди будут сразу переходить и экспериментировать.

Вам может стать тесно в рамках публичной песочницы и вы захотите сделать свою. Это тоже не так сложно, потому что у нас есть две замечательные библиотеки редакторов кода в браузере. Первая — CodeMirror, она используется, например, в jsfiddle и Firefox DevTools. Вторая — Ace, она используется в Atom, многими любимом. Мы в APS-е не стали мелочится и сделали собственную публичную песочницу, как раз с использованием CodeMirror.

Изначально мы рассчитывали, что песочницей будут пользоваться новички, поэтому сделали так, что любые примеры из документации можно открыть в песочнице, а также сразу добавили автодополнение кода. И в этом тоже нет никакого рокет сайнса, ведь у нас есть JSON-словари нашего API и их можно просто скормить редактору кода. Причем так можно делать не только с браузерными редакторами. К примеру, мне удалось завести такое автодополнение кода в Sublime. Позже мы добавили выбор версии API, одновременную работу нескольких пользователей с одним фрагментом кода и прочее, но это всё необязательные рюшечки. Главное — совсем не сложно сделать простую песочницу с редактором кода и результатами в Iframe. И опять же, для React-а есть уже готовый генератор таких песочниц.

Взаимодействие с пользователем

Вот мы сделали документацию, сделали песочницу и кажется что на этом можно остановиться. Верно, но только если вы собирается остановится в развитии вашего API. Если вы хотите развивать его дальше, то лучше взаимодействовать со своими пользователями. Причем лицом к лицу, а не бросая им новую функциональность через как можно более высокую стену, чтобы не слышать их «благодарных” криков. Проще всего этого сделать с помощью каких-нибудь issues на GitHub-е или всевозможных чатиков и каналов в месенджерах. Но есть вещи о которых пользователи вам не расскажут. Например, у человека была проблема, он её как-то решил, даже пускай костылем, и он этот костыль любовно переносит ctrl-c/ctrl-v из проекта в проект. Но может оказаться, что такой сценарий вы не предусмотрели и в худшем случае пользователь мог даже залезть в какой-нибудь ваш приватный API. Как же с этим бороться?

Первый способ — это собирать различные метрики, то есть логировать вызовы методов и отсылать их куда-то. Можно отслеживать, какие создавались модули и виджеты, с какими параметрами и тому подобное. Разумеется, нужно ещё отслеживать окружение, в котором выполнялся ваш код (версии браузеров, мобильные устройства), потому что статистика по использованию браузеров в мире — вещь полезная, но ваши пользователи могут оказаться стильными/модными/молодежными, которые используют только современные браузеры, а вы зачем-то тратите время и силы на поддержку IE.

Второй способ взаимодействия больше подходит для крупных компаний, которые заинтересованы в использовании их публичного API — заводить специальные команды по обучению. Помните, как Яндекс нам всем мозг ковырял со своим БЭМом на различных субботниках и митапах? У нас в Odin тоже есть команда тренеров, которые катаются по всему миру и обучают людей APS-у. На занятиях тренеры видят, где у людей возникает больше всего затруднений, где они вставляют костыли, любовно переносимые из проекта в проект, тогда мы аккуратненько асфальтируем эти протоптанные людьми тропиночки и делаем им удобные дороги.

Обратная совместимость

Хорошо, мы наладили взаимодействие с пользователем, меняем API так, как они просят, делаем его лучше, лучше… И тут нас ожидает мина, которая называется обратная совместимость. Представьте, вы тихо мирно спите себе дома или нежитесь на райском острове в отпуске, и тут звонит начальник и кричит, что всё пропало, всё сломалось, сервер лежит, клиенты уходят, гипс снимают, сделай что-нибудь.

Вы начинаете вспоминать и понимаете, что там ничего не менялось уже месяц. Лезете разбираться — оказывается, там какая-то маленькая библиотечка обновила минорную версию, а тот, кто её поддерживает, решил, что метод А делает не то, что надо, и поменял его поведение. Но вы-то ожидали от метода старого поведения. И ваш код ожидал старого поведения. Если вы будете вести себя как владелец этой библиотечки, то очень быстро растеряете всех пользователей.

Как же с этим бороться?

Я не могу предложить здесь ничего оригинального: только тесты, тесты и еще раз тесты. Причем тесты не просто на покрытие кода, а на покрытие публичного API. Мы в Odin, подошли к этому совсем тоталитарно и проверяем на этапе pull-request-а, во-первых, деградацию по line of coverage, а, во-вторых, деградацию по публичному API. Поскольку у нас есть JSON-словари мы можем сопоставить их с отчетом о покрытии и выяснить какие методы не были покрыты тестами. Если такие появились, то проверка считается не пройденной и такой pull-request нельзя объединять с мастер-веткой.

Итого

Что нужно сделать, чтобы публичным API было приятно пользоваться?

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

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

Ну и в-третьих, нужно писать тесты. Причем заливая всё трехметровым слоем бетона, полностью контролируя любые изменения, то есть чтобы публичный API менялся только при изменении мажорной версии.

Источник

Wargaming Public API

Wargaming.net Public API — набор общедоступных программных интерфейсов, которые предоставляют доступ к проектам Wargaming.net, включая игровой контент, статистику игроков, данные энциклопедии и многое другое.

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

История развития публичных API

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

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

Года эдак с 2005 наблюдался вообще взрывообразный рост количества всевозможных API. Вот картинка с ProgrammableWeb, это подтверждающая:

Предпосылки создания Wargaming Public API

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

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

Собственно, в этом плане Wargaming ничем не отличается — как только «танки» стали популярными, сразу же возник спрос на информацию по профилям игроков, кланам, статистике, рейтингам, глобальной карте, энциклопедиям и т.д. Разумеется, начался парсинг сайтов в попытках вытащить эти данные. А как только вышел World of Tanks Assistant, на его API немедленно набросились страждущие.

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

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

Внутреннее взаимодействие компонентов «позади» API

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

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

Принципы взаимодействия

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

API компонента чаще всего представляет собой HTTP REST API. Вызов API может возвращать ответ как синхронно, так и асинхронно. Для асинхронных ответов используется Message Broker (RabbitMQ в нашем случае) по протоколу AMQP.

События также гоняются через RabbitMQ. Примером события может служить экспорт состояния аккаунта игрока после его изменения. Кроме того, например, после каждого боя в MQ экспортируется досье танка игрока, на котором он этот бой играл. Это позволяет игровому порталу показывать актуальную статистику игрока, когда бы он ни зашел ее посмотреть (ну, почти). При этом и без того загруженный игровой сервер не получает дополнительной нагрузки.

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

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

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

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

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

Немного статистики

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

Вот немного актуальных цифр для RU-реалма:

13 800 000

13 100 000

7 360 000

5 800 000

3 800 000

Приложения

Всего активных на текущий момент приложений — более 200. Цифры не самые большие, но среди приложений много достойных, а на некоторые, даже по очень грубой оценке, потрачено порядочно времени и усилий. Например:

Кстати, Wargaming вовсе не против того, чтобы хорошие приложения монетизировались и приносили доход своим разработчикам.

Developers Partner Program

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

В рамках этого проекта мы также хотели бы собрать разработчиков игровых модов и попытаться наладить с ними конструктивный диалог. Если API к данным сейчас закрывает многие потребности разработчиков, то у мододелов жизнь сильно сложнее. Надеюсь, нам удастся сделать ее немного приятнее. Собственно, именно поэтому весь проект целиком называется Wargaming Developers Partner Program, а не просто Public API.

Конкурс

Сейчас мы готовы перейти к следующему этапу поддержки проекта и взаимодействия с игровым сообществом — открытому конкурсу для разработчиков.

Wargaming Developers Contest будет направлен на поддержку разработчиков игровых модов, приложений и околоигровых сервисов. Мы уверены, что в сообществе много амбициозных ребят и им по силам сделать законченные проекты, реализующие идеи, которые Wargaming еще не видит или реализация которых откладывается в долгий ящик. Это может быть что угодно: интеграция с разными платформами и интерфейсами других сервисов, по-хорошему безумные пользовательские интерфейсы, концепция второго игрового экрана и многое другое.

Для всего этого в рамках Wargaming Developers Contest мы приготовили отличный призовой фонд; кроме того, уникальные и оригинальные проекты мы обязательно представим нашей многомиллионной аудитории.

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

Источник