Какой сценарий описывает использование публичного 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 менялся только при изменении мажорной версии.

Если вы работаете даже удаленно рядом с индустрией веб-разработчиков, можете быть на 100% уверены, что слышали эти три печально известных буквы: API .

О них разговоры раскиданы между нубами и экспертами:

«Почему я должен сделать вызов API? У него есть номер?»

«Простой вызов этого стороннего API поможет вам в этом».

«Мы создадим вам RESTful API; убедитесь, что ваша новая система хорошо работает с другими сервисами».

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

Зачем? Что ж, обучение правильному использованию API-интерфейсов может упростить, ускорить и усилить рабочий процесс разработки. Создание или интеграция API-интерфейсов приносит значительную пользу как для клиентов, так и для вас самих.

Как разработчики, вы часто слышите совет «не изобретай велосипед»:

шутка:
мудрый совет: не изобретай велосипед
программист: хорошо
никогда больше не пишет собственный код

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

Преимущества использования API
Что такое API на самом деле
Какие существуют типы API
Практические примеры использования API

Чтож, не пора ли погрузиться в это?

Преимущества API: зачем их использовать?

Одним из первых, самых важных этапов в моей карьере программиста было правильное понимание API.

Я до сих пор использую их каждый день.

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

Потому что обучение использованию API значительно повышает эффективность вашей разработки.

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

Во-вторых, многие проблемы разработки, с которыми вы столкнетесь, уже были решены кем-то до вас. Какую бы форму ни приняли эти существующие решения ( FaaS , библиотеки, веб-сервисы, SDK, контентные API и т. Д.), Вам, скорее всего, понадобится API для взаимодействия с ними.

Так что же такое API?

Ну, официальное, устрашающее определение звучит так:

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

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

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

Чтобы пролить свет на API, давайте перечислим, чем они НЕ являются:

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

• API это не просто интерфейс . Это и спецификация / формат и реализация.

• API не является GUI (графический интерфейс пользователя). Он не делает взаимодействия на графическом уровне; он работает исключительно на программном уровне , либо через язык программирования , либо через коммуникационный протокол.

API также не является веб-крючком(web-hook). Если вам трудно понять разницу между ними, вот вступление к веб-зацепкам.

Различные типы API

Все API не созданы равными.

Хотя они в основном преследуют одну и ту же цель, некоторые достигают ее лучше, чем другие. Поскольку это должно быть гладкое вступление, я не буду вдаваться в то, что делает API лучше, чем другие. Однако имейте в виду, что у людей действительно разные подходы к созданию API. Если вас интересует эта тема, найдите в Google «Шаблоны проектирования API» и «Парадигмы API». Или просто начните с этой статьи начального уровня

Конечные точки(endponts)

Цель API — сделать вашу жизнь как разработчика проще. Как они это делают? Объединяя совокупность функций / функций и выставляя эти функции через конечные точки (обычно шаблоны URL, используемые для взаимодействия с API). Эти конечные точки являются единственным способом взаимодействия с любым API. Каждая конечная точка будет иметь определенный формат для своих запросов и ответов — вы обычно найдете этот формат в документации API.

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

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

Как использовать API: практические примеры

Чтение и понимание документации API

Я не хочу слишком много расширять концептуальные объяснения здесь. Итак, давайте проанализируем действительно простой API, чтобы разобраться в этом и посмотрим, как он работает в реальном сценарии. Для этого мы возьмем собственный объект JavaScript Math ( откройте документацию здесь https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math ).

Из документов видно, что каждая функция объекта описывает, каким должен быть формат ввода (число, массив чисел и т. Д.), И описывает формат вывода. Обратите внимание, однако, что ничего не упоминается относительно логики для запуска этих функций. Например, если вы запустите консоль разработчика и Math.sqrt (без выполнения функции), вы получите что-то вроде ƒ sqrt() { [native code] } . Это дух API: независимо от того, вызываете ли вы один из API вашей операционной системы или веб-API, эти принципы сохранятся.

Основные примеры использования API

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

Теперь, если вы следите за нашим блогом, я подозреваю, что вы больше заинтересованы в веб-API, чем что-либо еще. Итак, давайте углубимся в конкретные варианты использования. Обратите внимание, что мы будем использовать Postman в наших примерах. Конечно, этот Rest Client связан с веб-средой, но такие инструменты обычно существуют и в других средах. Стоит взглянуть на инструменты, предоставляемые для данной среды, прежде чем начать играть с ней; может сэкономить вам много времени.

Если вы хотите следовать за нами, вам необходимо скачать клиент Postman .https://www.getpostman.com/

Использование публичного API для извлечения данных

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

Мы будем использовать Dog API ! Это не только забавный API, но и не требует никакой аутентификации. Кроме того, это HTTP REST API, что означает, что это веб-API. Поскольку он связан с этой средой, он требует от нас соответствия некоторым специфическим особенностям протокола: в данном случае HTTP-глаголы (GET, PUT, POST, DELETE и т. Д.). В нашем примере мы будем просты и будем использовать только глагол GET. В любом случае API не позволяет поддерживать что-либо еще. Большинство общедоступных API-интерфейсов позволяют вам только использовать данные, а не публиковать их, такой как, глагол GET .

Давайте запустим Postman и посмотрим, как выглядит его пользовательский интерфейс.

Мой пользовательский интерфейс использует темную тему, поэтому она может немного отличаться от вашей.

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

Глагол по умолчанию должен быть GET, чтобы вы могли оставить его таким и ввести следующий URL: https://dog.ceo/api/breeds/list/all

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

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

Классный факт: этот маленький проект также с открытым исходным кодом, так что вы можете заглянуть сюдаhttps://github.com/ElliottLandsborough/dog-ceo-api .

Обработка аутентификации с помощью частного API

Теперь вы должны лучше понять, как разные части работают вместе, когда дело доходит до API. Итак, давайте сделаем более сложное руководство, которое включает в себя аутентификацию. Я собираюсь использовать наш собственный API-интерфейс приложения для разработчиков здесь.https://snipcart.com/ecommerce-for-developers

Здесь мы будем использовать код только для взаимодействия с API Snipcart https://docs.snipcart.com/api-reference/introduction . Вы можете закрыть Почтальон, но держите его под рукой; хорошо использовать такой инструмент при запуске с API.

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

Создайте новую папку для этого проекта, используйте npm init в папке и загрузите ваш текстовый редактор. Теперь создайте файл index.js , затем откройте файл package.json . В него добавьте следующие строки в объект верхнего уровня:

"bin": { "discounts": "./index.js" }

Нам также понадобится пакет commander для анализа входных данных от клиента. Итак, запустите npm install --save commander в текущей папке. Мы также будем использовать небольшую библиотеку для создания идентификаторов; Вы можете установить его с помощью npm install --save shortid . Пока мы работаем, давайте также запустим npm install --save request lib, чтобы нам было проще совершать HTTP-вызовы. Вернитесь в файл index.js и вставьте этот код:

#!/usr/bin/env node
var program = require('commander');
var shortid = require('shortid');
var request = require('request');

function CreateDiscount(){
    var discount = {
        name: '20% OFF',
        trigger: 'Code',
        type: 'Rate',
        rate: 20,
        maxNumberOfUsages: 1,
        code: shortid.generate()
    }

    request({
        url: "http://app.snipcart.com/api/discounts",
        auth: {
            'user': 'YOUR_API_KEY'
        },
        method: "POST",
        json: true,
        body: discount
    }, function (error, response, body){
        console.log(body.code);
    });
}

program
    .arguments('<number>')
    .action(function(number) {
        for(var i = parseFloat(number); i > 0; i--){
            CreateDiscount();
        }
    })
    .parse(process.argv);

Давайте просто сосредоточимся на функции request здесь. Здесь мы делаем внешний вызов API для Snipcart. Вы можете видеть, что мы передаем method: “POST” в метод. Это потому, что мы хотим публиковать данные в API Snipcart. Указав этот метод, API будет правильно отображать действие, чтобы он мог прочитать тело запроса, в котором находятся данные о скидках.

Интересная функция API, которую мы еще не использовали, — это аутентификация. Все остальные наши примеры были на общедоступных API: они не требуют аутентификации. Но в реальных сценариях для большинства используемых вами API, вероятно, потребуется некоторая аутентификация, например, API Twitter или Google Maps API. Это стандартный «шаблон» в мире API. Наши клиенты не были бы так счастливы, если бы мы позволили кому-либо создавать скидки в их магазине.

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

Для нашей цели мы передаем ключ API непосредственно в запросе, и ура сервер нас узнает! Затем он может выполнить запрос, относящийся только к нашей учетной записи.

Если вы хотите протестировать наше маленькое приложение, вы можете запустить npm install -g в каталоге проекта и просто запустить discounts x чтобы создать скидки x количество раз. Вы можете зайти в свою панель Snipcart ( навсегда бесплатные аккаунты в тестовом режиме) и убедиться, что скидки были созданы правильно. Вы можете себе представить, насколько мощным это может быть: если бы вам пришлось создать 200 таких скидок, это потребовало бы слишком много времени, чтобы сделать это через наш пользовательский интерфейс. Однако, когда вы ознакомитесь с работой API, это можно сделать за считанные минуты. Код также можно использовать повторно, так что если вам нужно сделать то же самое через месяц, ну, вы уже готовы!

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

Заключительные мысли

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

Несколько выносов:

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

Теперь наш последний пример не готов к «производству», но он дает вам хорошее представление о том, как все может выглядеть в реальной жизни. Есть много вещей, которые мы могли бы улучшить, например, позволить пользователю выбрать тип скидки и т. Д. Мы могли бы также использовать созданные коды для отправки их по электронной почте непосредственно в той же функции, а не просто регистрировать их. Если бы у нас были повышенные потребности в наших инструментах скидок, мы могли бы сами написать API. Оттуда мы могли бы даже создать пользовательский интерфейс, который взаимодействует с нашим API, если мы захотим. Во всяком случае, я надеюсь, что вы поняли идею сейчас!

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

И вот тут начинается настоящее веселье.

©Перевод статьи https://snipcart.com/blog/apis-integration-usage-benefits

Edit me

После раздела «Обзор API» обычно идет раздел «Начало работы», в котором подробно описываются первые шаги, которые пользователи должны пройти для использования API. Этот раздел часто включает весь процесс от начала до конца, сжатый настолько просто, насколько это возможно.

Цель раздела “Начало работы”

Раздел «Начало работы» это как Hello World для разработчиков, только с API. “Начало работы” ведет за руку пользователя от начала до конца при создании простейшего возможного вывода с системой. Для Hello World самым простым выводом является сообщение «Hello World». Для API это может быть успешный ответ на самый простой запрос.

И Hello World и “Начало работы” преследуют одну и ту же цель: показать пользователю, как использовать инфраструктуру, API или какую-либо другую систему, для получения простого и легкого результата, чтобы пользователи получили полное представление о работе системы, API и т.д.

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

Раздел “Начало работы” может содержать следующие пункты:

• Войти в аккаунт;
• Получить API ключ;
• Создание запроса
• Оценка ответа.

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

Кнопка Run in Postman

В разделе “Начало работы” можно рассмотреть возможность добавления кнопки Run in Postman. (Postman — это клиент REST API GUI, который мы изучили ранее в разделе Отправка запросов в Postman.) Если есть конечные точки API, интегрированные с Postman, можно экспортировать свои коллекции Postman в виде виджета для встраивания в HTML-страницу.

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

Чтобы добавить кнопку Run in Postman, можно импортировать спецификацию OpenAPI в Postman или ввести информацию об API вручную. Стоит изучить раздел “Postman/docs”, как создать кнопку Run in Postman.

Множество демонстраций Run in Postman можно посмотреть здесь. Многие из этих демонстраций перечислены в сети API Postman.

Вот демо Run in Postman с использованием конечной точки weather API OpenWeatherMap (с которой мы работали раннее ):

Если нажать на кнопку, будет предложено открыть коллекцию в клиенте Postman:

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

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

Если в документации еще нет функции Try it out, кнопка Run in Postman предоставляет такую интерактивность простым способом, не требуя жертв со стороны единственного источника знаний для документации.

Недостатком является то, что в Postman не попадают описания параметров и конечных точек. Кроме того, если пользователи незнакомы с Postman, им может быть трудно понять, как им пользоваться. Редакторы Try it out, которые запускаются непосредственно в браузере, как правило, более просты и лучше интегрируют документацию.

Примеры разделов “Начало работы”

Ниже приведены несколько примеров разделов “Начало работы” в API. Если сравнить различные разделы «Начало работы», можно увидеть, что некоторые из них являются подробными, а некоторые — высокоуровневыми и краткими. В общем, чем дольше можно вести разработчика за руку, тем лучше. Тем не менее, раздел должен быть кратким, а не многословным с другой документацией. Ключевым моментом является то, чтобы показать пользователю полный, от и до, процесс работы с API.

Paypal

“Начало работы” Paypal содержит довольно много деталей, начиная с авторизации, запросов и других деталей до первого запроса. Хотя этот уровень детализации не так краток, он помогает сориентировать пользователей на необходимую им информацию. Чистый и понятный формат.

Twitter

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

Parse Server

Раздел “Начало” работы в Parse Server содержит большое количество деталей и подробное описание различных этапов. Для более подробных шагов по подключению вашего приложения и запуску сервера в другом месте, в разделе размещена ссылка на дополнительную информацию.

Adsense

“Начало работы” Adsense выделяет некоторые основные предпосылки для начала работы на платформе. После того, как вы настроитесь, он предоставляет «краткое руководство по началу работы». Такое руководство знакомит пользователей с простым сценарием от начала до конца, помогая им понять продукт и его возможности.

Aeris

Начало работы в сервисе погоды Aeris предоставляет информацию для настройки приложения, а затем делает запрос на одном из нескольких популярных языков. Хотя показ кода на определенных языках, несомненно, более полезен для программистов, использующих данный язык, примеры кода могут быть неуместны для других пользователей (например, разработчики Java могут найти код Python неуместным, и наоборот). Фокусировка на определенном языке часто является компромиссом.

Watson and IBM Cloud

В разделе “Начало работы” Watson и IBM Cloud перечислены три шага. Тем не менее, это не полное руководство по началу работы. Пользователь может только выбрать сервис для своего проекта. В итоге кодировать начинаем с помощью Watson Dashboard.

В идеале, раздел “Начало работы” должен помочь пользователю увидеть ощутимые результаты, но возможно ли это или нет, зависит от API.

👨‍💻 Практическое занятие: Раздел “Начало работы”

В своем найденном опен-сорс проекте найдем раздел “Начало работы” и ответим на следующие вопросы:

• Есть ли у API раздел “Начало работы”?
• Описан ли процесс начала работы от и до в разделе?
• Можно ли успешно выполнить все шаги в разделе?
• Сколько времени занимает освоение раздела?
• Отобразятся ли предположения о вашем техническом уровне в документации при попытках упростить инструкцию?

🔙

Go next ➡

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

Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу «чем больше, тем лучше».

Если ваши  документы не читают, не понимают, или вы не знаете с чего начать описывать интеграцию,  то эта статья для вас.

Я тех. лид системных аналитиков и прошла долгий путь к шаблонам документации в разных компаниях.

С чего все начинается

Чаще всего у системного аналитика болит от того, что его техническое задание (ТЗ) не читают. Разрабатывают как поняли, тестируют как услышали, а заказчик ждет вообще другое. Еще болит, а как описать задание разработчику, если в компании нет шаблона?

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

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

Перед нами команда, которая разрабатывает новые интеграции.

Задача аналитика — описать интеграцию систем (спроектировать API).

Для чего команде документ

Product owner

В описании ищет ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Разработчик

Без документа не понимает как ему делать задачу, поэтому вопросы у него такие:

Что мне делать: параметры запроса-ответа?
В какие системы сходить за данными или передать?

Тестировщик

Прочитав описание интеграции, сможет ответить на вопросы:

Как бы это все сломать: какие ошибки можно сделать?
Где найти тестовые запрос-ответ?
С какими системами есть взаимодействие, чтобы проверить весь путь?

Аналитик другой команды

Этому человеку нужна любая документация, потому что у него один вопрос:

Как переиспользовать или доработать сервис, чтобы ничего не сломать?

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

Из чего состоит шаблон

В шаблоне на интеграцию (API) будут разделы:

Основная информация
Запрос/Ответ
Входные параметры
   Проверки
Выходные параметры
   Положительный ответ
   Ответ с ошибками
Описание интеграции
Интеграции
   Интеграция с сервисом №1

Почему именно такая структура?

Спокойствие, только спокойствие, сейчас все расскажу!

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

Основная информация

В разделе можно найти ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Запрос/Ответ, Входные и выходные параметры

В этих разделах документа есть информация:

Что мне делать: параметры запроса-ответа?
Где найти тестовые запрос-ответ?
Как бы это все сломать: какие ошибки можно сделать?

Описание интеграции

Здесь есть ответы на вопросы:

В какие системы сходить за данными или передать?
С какими системами есть взаимодействие, чтобы проверить весь путь?
Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Как применить шаблон на практике

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

В шаблоне есть:

Основная информация

Запрос/Ответ

Входные параметры

Выходные параметры

Описание интеграции

Для построения сервиса использовался инструмент plantuml. Работа с ним описана в статье https://habr.com/ru/post/661931/

Посмотреть реализованный сервис можно по ссылке https://petstore.swagger.io/#/pet/addPet. Для удобства описания были придуманы некоторые проверки и коды ошибок

Интеграции

Вы получили шаблон технической документации на API . Скачать шаблон google docs можно по ссылке

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

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

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

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

Что такое API?

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

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

Время для примера. Допустим, вы хотите увидеть последний кассовый хит. Вашим первым шагом может быть поиск, где и когда он играет на сайте онлайн-продажи билетов, таком как Fandango. После ввода почтового индекса и выбора даты вы нажимаете «перейти», и, вуаля, через несколько секунд появляется список сеансов в ближайших кинотеатрах. Вот как это выглядит для конечного пользователя.

Источник

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

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

Как работают API?

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

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

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

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

Источник

Но допустим, что в ресторане приходит слишком много гостей и им не хватает места. Допустим, это происходит по мере роста популярности ресторана. Что тогда? Вот тут и нужны ключи API.

Что такое ключ API?

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

Хотя этот метод не так безопасен, как токены аутентификации, он имеет некоторые преимущества по сравнению с базовой аутентификацией, для которой требуются только имя пользователя и пароль.

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

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

Для чего используются API?

Возможно, лучше спросить, для чего не используются API. Хотите встроить фотографии из Instagram в свое приложение для электронной коммерции? Для этого есть API. Хотите предоставить мгновенный доступ к тысячам отелей в своем блоге о путешествиях? Для этого есть API. Хотите интегрировать переводчик Йоды на свой сайт фанфиков по «Звездным войнам»? Если вы можете в это поверить, для этого есть API.

Эти примеры раскрывают некоторые из наиболее распространенных причин, по которым компании используют API. Большинство клиентов, использующих API, хотят, чтобы сервер выполнял основные функции. Эти запросы могут быть записаны как URL-адреса, так что обмен данными между клиентом и сервером определяется правилами протокола передачи гипертекста (HTTP). Четыре основных запроса сервера:

• GET: получить ресурс
• POST: для создания нового ресурса
• PUT: для редактирования или обновления существующего ресурса
• УДАЛИТЬ: удалить ресурс

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

Типы API

1. Частные API.
2. Партнерские API.
3. Публичные API.

Эти имена интуитивно понятны, поэтому мы кратко коснемся каждого типа ниже.

Частные API

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

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

Партнерские API

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

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

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

Публичные API

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

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

Преимущества API

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

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

Преимущества для потребителей API

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

Продуктивность

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

Удовлетворенность пользователей

Компании хотят обеспечить своим пользователям лучший опыт. Редко один продукт может удовлетворить и предвосхитить все потребности и ожидания. Вот почему они используют API для расширения функциональности своих продуктов. Например, OpenTable использует API JavaScript Карт для встраивания интерактивной карты на свой сайт, позволяя пользователям прокладывать маршруты от их домов до ближайших ресторанов всего за несколько кликов. Если вы не знакомы с сайтом, посмотрите этот снимок экрана с обзором стейк-хауса в Индиане.

Источник

Инновации

Позволяя разработчикам – сторонним или внутренним сотрудникам – повторно использовать программные компоненты, API-интерфейсы дают им возможность сосредоточиться на разработке новых решений, а не на повторении уже выполненной работы. Вернемся к приведенному выше примеру. Без Google Maps API разработчикам OpenTable пришлось бы посвятить свое время и ресурсы рисованию собственной карты и предоставлению картографических данных в реальном времени для включения этой функции на свой сайт. Что еще хуже, независимо от того, сколько времени они потратят, было бы почти невозможно сделать его таким же подробным и надежным, как существующее решение Google. Таким образом, вместо того, чтобы тратить время на то, чтобы изобрести колесо, API-интерфейсы позволяют разработчикам сосредоточиться на создании новых инструментов и функций, которые принесут больше пользы их пользователям.

Преимущества для поставщиков API

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

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

Доход

Простой ответ – деньги. Google, Yelp, Facebook и тысячи других компаний делают свои API общедоступными и монетизируют их, чтобы они стали дополнительными источниками дохода. Фактически, в некоторых компаниях API являются основным источником дохода. Согласно недавнему отчету MuleSoft Inc., 35 процентов сегодняшних технологических лидеров генерируют более четверти дохода своих организаций в результате использования API.

Шкала

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

Инновации

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

Как использовать API

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

Выбор API

Перво-наперво вы захотите найти API, подходящий для вашего бизнеса. Возможно, вы уже положили глаз на API, особенно если вас интересует один из больших париков, таких как API Facebook. Или вам может потребоваться поиск по стоимости – вы можете начать с бесплатного API, прежде чем переходить, например, к платным API, – или по категории или любому количеству других фильтров. Вы можете вводить ключевые слова прямо в поисковой системе или просматривать торговые площадки API, такие как Marketplace Rapid API.

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

Просмотр документации API

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

Написание запроса

Далее вам нужно будет написать свой запрос. Самый простой способ – использовать Postman или другой онлайн-клиент HTTP, у которого есть инструменты, которые помогут вам структурировать запросы. Вам по-прежнему необходимо понимать и получать некоторую информацию из документации API, но вам не потребуется много знаний в области программирования, чтобы добиться успеха.

Вы также можете пойти по пути DIY и создать URL-адрес, настроив примеры в существующей документации API, чтобы получить желаемый результат. Это может показаться пугающим, но для этого не обязательно быть разработчиком. Чтобы доказать это, давайте рассмотрим простой пример от TechnologyAdvice.com.

Допустим, вы хотите запросить погоду для конкретного города с помощью API Open Weather Map. Просматривая документацию, вы найдете этот пример URL: api.openweathermap.org/data/2.5/weather?q={city name}. Сладкий! Теперь все, что вам нужно сделать, это скопировать и вставить этот URL-адрес в браузер, ввести название города, о котором вы хотите знать, и указать свой ключ API. Если вы хотите знать погоду в Нэшвилле, ваш URL-адрес будет выглядеть так: api.openweathermap.org/data/2.5/weather?q=Nashville,TN&APIID={numberslettersnumbersletters}.

На этом этапе онлайн-уроки действительно могут прийти на помощь. Например, это видео на YouTube объясняет, как использовать API для извлечения данных о местоположении из Google Maps, а затем использовать эти координаты для поиска ближайших фотографий в Instagram.

Это видео, как и многие другие ресурсы, предназначенные как для разработчиков, так и для не-разработчиков, посвящено определенному типу API, который считается более простым в использовании, чем другие. Эти API-интерфейсы называются REST API.

REST API

API-интерфейсы REST соответствуют ограничениям стиля архитектуры программного обеспечения, называемого «передача репрезентативного состояния», что делает API-интерфейсы относительно простыми в использовании и обнаружении. REST делает данные и функции доступными в виде ресурсов, которые представлены уникальными URL-адресами. Чтобы запросить ресурс через REST API, например Open Weather Map API, вам просто нужно указать его URL.

В типичном REST API ресурсу будут назначены два шаблона URL: множественное число (для обозначения всех ресурсов) и единственное число (для указания одного ресурса). Их также называют конечными точками. Вы можете догадаться, почему? Потому что они идут в конце URL-адреса.

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

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

WordPress имеет REST API, который позволяет разработчикам удаленно создавать, читать и обновлять контент WordPress, передавая объекты JSON между клиентами и серверами. Другими словами, позволяя разработчикам легко структурировать способ получения данных на сервере и с сервера, они могут тратить меньше времени на доступ к нужным им данным и больше времени на улучшение взаимодействия с пользователем.

ОТДЫХ против мыла

REST обычно соприкасается с протоколом простого доступа к объектам (SOAP), еще одним способом создания приложений, работающих через HTTP. REST считается более простой альтернативой SOAP, поскольку он требует написания меньшего количества кода для выполнения задач и следует менее жесткой структуре и логике, чем SOAP. Еще одна причина, по которой люди любят REST: он предоставляет множество соглашений, но оставляет множество решений на усмотрение человека, разрабатывающего API.

Вот простой тест, если вы выбираете между REST и SOAP для вашего API: если вам нужна гибкость, используйте REST. Если вам нужна стандартизация, используйте SOAP.

Примеры API

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

Twitter API

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

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

API Instagram

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

API YouTube

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

API HubSpot

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

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

Будущее цифровой экономики

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

Таким образом, API меняют не только способ ведения бизнеса компаниями. Они меняют то, как компании думают о бизнесе.

Источник записи: https://blog.hubspot.com

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

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

API могут быть разными. Самый востребованный из них — REST. О нём и пойдёт речь в этой статье.

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

Слово REST — акроним от Representational State Transfer, что переводится на русский как «передача состояния представления», «передача репрезентативного состояния» или «передача „самоописываемого“ состояния».

В отличие от, например, SOAP API, REST API — не протокол, а простой список рекомендаций, которым можно следовать или не следовать. Поэтому у него нет собственных методов. С другой стороны, его автор Рой Филдинг создал ещё и протокол HTTP, так что они очень хорошо сочетаются, и REST обычно используют в связке с HTTP. Хотя новичкам нужно помнить: REST — это не только HTTP, а HTTP — не только REST.

Иногда, помимо акронима REST, можно встретить слово RESTful. Это не термин, но в сообществе его применяют к веб-сервисам, которые соответствуют REST-архитектуре. RESTful используют как прилагательное.

Всего в REST есть шесть требований к проектированию API. Пять из них обязательные, одно — опциональное:

• Клиент-серверная модель (client-server model).
• Отсутствие состояния (statelessness).
• Кэширование (cacheability).
• Единообразие интерфейса (uniform interface).
• Многоуровневая система (layered system).
• Код по требованию (code on demand) — необязательно.

Чтобы разобраться в них подробнее, нужно понимать, что в вебе называют ресурсами. Ресурсы — это любые данные: текст, изображение, видео, аудио, целая программа. Например, HTML веб-страницы, на которой вы сейчас находитесь, — тоже ресурс.

Это требование отделяет друг от друга два понятия: клиент и сервер.

Сервер — программа, в которой хранятся и обрабатываются ресурсы. Сервер может располагаться на одном или нескольких компьютерах; но даже в одном компьютере может быть несколько виртуальных серверов. Допустим, изначально HTML-код этой статьи хранился где-то на серверах Skillbox.

Клиент — программа, которая запрашивает у сервера доступ к ресурсам. Для этого она использует API. Когда ваш браузер запрашивает у сервера Skillbox эту веб-страницу, он выступает в роли клиента.

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

Представим, что вы делаете сервис для учёта деловых переписок. Сами переписки хранятся на сервере, а доступ к ним можно получить из мобильного приложения. Оно не будет хранить никаких данных — только отправлять запросы на сервер, получать ответы и отображать их на экране смартфона.

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

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

Второй принцип настолько важен, что даже отражён в названии архитектурного стиля — Representational State Transfer. Это значит, что на сервере не хранится никаких данных о прошлых взаимодействиях с клиентом — каждый запрос должен содержать всю информацию для его обработки.

Например, кто-то запросил последнее сообщение от ООО «Рога и копыта». В этом запросе содержится вся информация, которая нужна серверу, чтобы дать корректный ответ.

Если клиент потом хочет получить предпоследнее сообщение, то он не может просто сказать: «Дай мне соседний ресурс» — ему нужно заново составить полный запрос по всем правилам.

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

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

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

Однако тут тоже важно подойти к делу без излишнего фанатизма и не кэшировать всю информацию подряд. Во-первых, для этого потребовались бы слишком большие объёмы памяти. Во-вторых, какие-то данные (скажем, количество исходящих писем) со временем могут устаревать — зачем же держать этот неактуальный хлам в кэше? Именно поэтому в каждом ответе сервера на запрос есть пометка о том, можно ли его кэшировать.

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

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

Для реализации единообразного интерфейса в REST API используется принцип HATEOAS (Hypermedia as the Engine of Application State).

До сих пор мы рассматривали сервер как единую сущность. Но его структура куда сложнее. Между ним и клиентом есть несколько промежуточных узлов, выполняющих вспомогательные функции, — прокси-серверы.

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

Никто из участников цепочки не знает всего пути, который проходит запрос, — только своих «соседей» справа и слева. Ни клиент, ни один из прокси-серверов не знает, к кому он обращается — к основному сервису или к другому прокси. В REST API это работает в обе стороны: никакие серверы (ни основные, ни прокси) не знают, кому отправляют ответ и уходит ли он куда-то дальше.

Этот принцип означает, что сервер в ответ на запрос может отправить исходный код, который выполняется уже на стороне клиента. Благодаря этому можно передавать целые сценарии. Например, динамические элементы пользовательского интерфейса, написанные на JavaScript.

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

Так как REST — архитектурный подход, а не протокол, в нём не заложено никаких конкретных методов. Но чаще всего его применяют вместе со стандартом HTTP, в котором заложены собственные методы.

Если кратко, то в HTTP прописан набор действий, который можно описать аббревиатурой CRUD: create — «создать», read — «прочитать», update — «обновить», delete — «удалить».

Для каждого такого действия существуют один или несколько глаголов — это и есть методы. Например, GET для чтения, а PUT и PATCH — для разных видов обновления. Глагол-метод применяется к URL-адресу нужного ресурса, который в «предложении» выполняет роль существительного.

Подробнее о работе протокола HTTP и его методов вы можете прочесть в нашей статье.

Архитектурный стиль REST — самый распространённый подход к проектированию API. Вот в каких случаях его применяют:

• пропускная способность соединения с сервером ограничена;
• нужно соединить мобильные приложения с серверными;
• проект разбит на микросервисы;
• сервис предоставляет свои возможности другим разработчикам;
• используется AJAX;
• известно, что систему нужно будет масштабировать.

Как мы видим, REST API не случайно стал таким популярным. Повторим основные его отличия:

• REST — это архитектурный стиль API. Он не ограничивается никакими протоколами и не имеет собственных методов. Но обычно в RESTful-сервисах используют стандарт HTTP, а файлы передают в формате JSON или XML.
• Есть шесть принципов, на которых строится REST: клиент-серверная модель, отсутствие состояния, кэширование, единообразие интерфейса, многоуровневая система, код по требованию. Последний из них необязателен.
• REST-подход к архитектуре позволяет сделать сервисы отказоустойчивыми, гибкими и производительными, а при их масштабировании и внесении изменений не возникает больших сложностей.