Если вы работаете даже удаленно рядом с индустрией веб-разработчиков, можете быть на 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