Разработка JavaScript API: 5 принципов написания встраиваемых скриптов
Наверняка вы сталкивались с принципами (пусть и противоречивыми) о написании модулей и классов на JavaScript. Когда мне понадобилось написать встраиваемый в веб-страницу cкрипт, который предоставляет API для работы определённого сервиса, то я не смог найти достойных рекомендаций о проектировании подобных скриптов.
Итак, вот (довольно очевидные) требования к скрипту, с которыми я столкнулся:
- он будет встраиваться в страницы сторонних веб-приложений;
- он должен выполнять свою работу качественно;
- он должен загружаться быстро;
- он не должен (непредсказуемо) влиять на работу веб-приложения;
- должен соответствовать требованиям безопасности;
- … // много чего ещё 🙂
Из реальной практики родились принципы, описанные ниже. Это не полностью уникальные идеи, а скорее сборка лучших практик, которых я видел в чужих решениях, например в библиотечках google analytics и jquery.
1. Система сборки
Она нужна. Сначала кажется, что можно просто всё держать в одном файле (можно даже с этого начать), но потом становится ясно, что сборка необходима. Потому что используются сторонние библиотечки. Потому что есть несколько вариантов поставки скрипта. Потому что скрипт может подгружать файлы ресурсов по мере необходимости. И об этом стоит думать сразу, даже когда вы ещё держите весь скрипт в одном файле.
Как собирать? Только конкатенация. Потому что основной скрипт должен загружаться быстро, то есть одним файлом.
Это не значит, что нужно всё залить в один файл, и надеяться, что всё будет хорошо. Необязательные, дополнительные возможности нужно подгружать лишь тогда, когда клиент библиотечки вызывает соответствующие методы. Но ядро должно загрузиться быстро, хорошо закэшироваться и сразу предоставить клиенту API.
Весь скрипт при этом надо завернуть в один scope. Очевидно? Да.
(function () < // Здесь будет твой код >());
Кстати, чтобы обернуть код в scope с помощью Grunt, используйте options banner и footer :
concat: < injectScriptProd: < src: [. ], dest: 'someScript.js', options: < banner: '(function()());' > >,
2. Переключение между локальной и продакшн конфигурацией
Чтобы можно было легко управлять сборками и конфигурациями, мне очень помогло завести одну переменную config , положить её в отдельный файл configDev.js или configProd.js и иметь отдельные сборки скрипта. А вариантов сборок по-другим причинам потребовалось больше двух. В результате, наличие этих простых файлов очень облегчило мне и сборку, и код, и жизнь. При конкатенации просто указываете, из каких файлов собрать скрипт, — и цельный файл-скрипт готов.
Плохая практика: иметь замещаемые переменные по всему JavaScript-коду вида: /someApi . Портит читаемость кода, медленнее собирается. И хочется, чтобы grunt watch работал действительно быстро, не правда ли?
Пример нашего prod config-файла:
var config = < server: "https://www.yourserver.com/api/", resourcesServer: "https://www.yourserver.com/cdn/", envSuffix: "Prod", globalName: "yourProjectName" >; // Маленький, да удаленький!
3. Как передать API наружу?
Есть разные способы, но сейчас делаем так:
window[config.globalName] = yourApiVar;
- Тестировать несколько версий библиотечки на странице, причём так, что они друг-другу не мешают.
- Весь скрипт поместить в один закрытый scope.
- (Если вдруг понадобится) решать проблемы с совместимостью. Мы ведь будем знать, что управление экземпляром API происходит в коде самого скрипта, а не в коде клиента библиотечки. И поэтому у нас есть полный контроль над всеми экземплярами.
4. “Правильная” система модулей
Я знаю, чтобы я здесь ни сказал, в меня полетят гнилые помидоры от людей, которые предпочитает другую систему модулей. Начинаем.
Правильно делать так:
var module = (function () < // for each module have this structure var someInnerModuleVar; // здесь мог бы быть твой гениальный код return < publicMethod: publicMethod >; >());
А почему именно так? Ответ очевиден: когда вы сконкатенируете код таких модулей, всё будет работать безо всяких библиотечек для модулей.
5. Инициализация API
Если в вашей библиотечке есть хоть какая-то инициализация (а она там есть, даже если вы думаете по-другому), то вынесите её в отдельный метод. Можно даже создать отдельный метод для инициализации в каждом модуле. И вызывать их потом явно и с чётким пониманием, как это работает и в какой последовательности.
Для первого раза, наверное, хватит. Вот структура получившегося модуля:
(function () < 'use strict'; var config = <>; var sharedState = <>; var module = (function () < var someInnerModuleVar; // крутой js код return < publicMethod: publicMethod, init: init >; >()); start(); >());
Если у вас есть идеи, как улучшить шаблон, то буду рад их услышать. Я в основном писал на java, этот проект, — мой самый интенсивный опыт в JavaScript. Напишите идеи по улучшению в комментариях.
Ещё думаю написать про работу с cookies , localStorage , db, network. Напишите, какие темы наиболее интересны.
- Разработка
- javascript
- лучшие практики
API СКРИПТЫ И ОСОБЕННОСТИ ИХ ИСПОЛЬЗОВАНИЯ Текст научной статьи по специальности «Компьютерные и информационные науки»
Аннотация научной статьи по компьютерным и информационным наукам, автор научной работы — Палаш Б.В.
В статье описываются основные принципы работы API скриптов, рассказана их важность в современном программировании. Рассматриваются основные способы защиты и передачи информации при работе с удаленными приложениями.
i Надоели баннеры? Вы всегда можете отключить рекламу.
Похожие темы научных работ по компьютерным и информационным наукам , автор научной работы — Палаш Б.В.
ОСНОВНЫЕ ПРИНЦИПЫ РАБОТЫ АЛГОРИТМА РАСПРЕДЕЛЕНИЯ СТУДЕНТОВ ПО НАУЧНЫМ РУКОВОДИТЕЛЯМ В СРЕДНИХ И ВЫСШИХ УЧЕБНЫХ ЗАВЕДЕНИЯХ
Разработка платформы для управления инфраструктурой интернета вещей
Исследование методов межпроцессного взаимодействия в информационной системе с горизонтальным взаимодействием
Разработка синтаксического анализатора для снятия данных о состоянии атмосферного воздуха Красноярского края с сайта krasecology. Ru
АКТУАЛЬНЫЕ ВЕБ-УЯЗВИМОСТИ СЕРВИСОВ ФИНАНСОВО-БАНКОВСКОГО СЕКТОРА И СПОСОБЫ ЗАЩИТЫ ВЕБ-ПРИЛОЖЕНИЯ
i Не можете найти то, что вам нужно? Попробуйте сервис подбора литературы.
i Надоели баннеры? Вы всегда можете отключить рекламу.
API SCRIPTS AND FEATURES OF THEIR USE
This article describes the basic principles of API scripts, describes their importance in modern programming. The main methods of protection and transmission of information when working with remote applications are considered.
Текст научной работы на тему «API СКРИПТЫ И ОСОБЕННОСТИ ИХ ИСПОЛЬЗОВАНИЯ»
Палаш Б.В. студент 2 курса
Хакасский государственный университет им. Н. Ф. Катанова
научный руководитель: Голубничий А.А.
Россия, г. Абакан
API СКРИПТЫ И ОСОБЕННОСТИ ИХ ИСПОЛЬЗОВАНИЯ
Аннотация: В статье описываются основные принципы работы API скриптов, рассказана их важность в современном программировании. Рассматриваются основные способы защиты и передачи информации при работе с удаленными приложениями.
Ключевые слова: API, MD5, Передача данных, Программное взаимодействие, Алгоритмы хеширования
Palash B. V. student
Katanov Khakass State University Russia, Abakan Scientific supervisor: Golubnichiy A.A.
API SCRIPTS AND FEATURES OF THEIR USE
Abstract: This article describes the basic principles of API scripts, describes their importance in modern programming. The main methods of protection and transmission of information when working with remote applications are considered.
Key words: API, MD5, Data transmission, Programmatic interaction, Message Digest
Каждый разработчик или команда разработчиков сталкивались с такой ситуацией, в которой необходимо расширить функционал своего проекта, но предоставлять доступ сторонним участникам процесса разработки к исходному коду проекта является не желательным, для решения таких проблем возможно использовать API скрипт.
API (программный интерфейс приложения, интерфейс прикладного программирования) — это набор классов и методов с помощью которых один программный продукт может взаимодействовать с другими программами [1].
Взаимодействие между программными продуктами посредствами API скриптов может происходить многими способами, но для рассмотрения были взяты два самых популярных — это методы POST и GET запросов.
GET это один из запросов которые поддерживает HTTP протокол. Данный запрос передаётся с использованием адресной строки браузера данный способ корректен и подходит, например, в случаях существования формы поиска. При вводе определенного текста в форму поиска данный текст передаётся посредством GET запроса и генерируется форма с результатами. При таком подходе мы сразу можем получить ссылку, которую можно переслать другому пользователю, и он при переходе сможет попасть сразу на
туже страницу с результатами поиска, что уберет необходимость просить пользователей забивать поисковый текст снова.
Главными минусами GET запросов является ограниченное количество данных, которые можно передать через него и возможность редактирования этих данных без каких-либо помех самим пользователем, что может негативно сказаться на работе проекта.
В отличии от GET, параметры POST запроса не отображаться в адресной строке браузера, по этой причине пользователь не в состоянии увидеть или изменить передаваемые данные. Так же POST запрос не страдает проблемой, связанной с длиной отправляемых данных (можно передавать данные или файлы любых объемов) [2].
Рисунок 1. Пример работы POST и GET запросов
Рассмотрев эти два самых популярных метода можно прийти к выводу что передача данных в API скрипт и получение данных от него обратно лучше производить с использованием именно POST запросов, что снимает лимит на количество передаваемых данных, а также практически исключит возможность случайной ошибки пользователя при передаче данных.
Способы для передачи данных очень важная часть любого API скрипта, однако, для того чтобы передать данные другому проекту нужно быть уверенным, что проект сможет прочитать такие данные. В связи с этим встает вопрос формата передачи данных в скриптах, ведь не все языки программирования хранят информацию одинаково и не во всех языках программирования существует такие типы данных. Для решения задачи взаимодействия скрипта и приложения возможно использовать JSON формат.
JSON — Это один из самых популярных форматов данных основанный на тексте [3]. С помощью простого синтаксиса возможно легко сохранять как простые цифры и строки, так и массивы, объекты, используя при этом не что иное как текст. Так же можно связывать объекты и массивы, что позволяет создавать сложные структуры данных. После перевода данные в форма JSON мы можем передавать его любым доступным нам способом ведь в результате мы получаем лишь текстовую строку. На данный момент библиотека JSON написана практически для каждого языка программирования, а в некоторых
входит в стандартный набор, но даже если в выбранном языке программирования нет данной библиотеки зная ее формат можно написать парсер с JSON самостоятельно.
Так как главным минусом API скриптов является общедоступность, то широко встает вопрос о безопасности такого способа взаимодействия.
Первым способом для обеспечения безопасности IP ключа является передача пост запросов по HTTPS протоколу. HTTPS (HyperText Transfer Protocol Secure) — это усовершенствованный протокол который взял свое начало от HTTP [4]. Данные передаваемы в HTTPS протоколе отправляются через криптографические протоколы SSL или TLS. В отличие от HTTP в котором для передачи используется 80 TCP-порт, для HTTPS по умолчанию используется TCP-порт 443. Использование данного порта дает возможность получить защиту от снифферских атак или от атака через посредника (Прямое подключение к каналу пользователя).
Главная проблема HTTPS связана с возможностью анализирования входящего и исходящего трафика. Суть данной проблемы связана с тем, что данные передаются по SSL или TLS протоколу данные протоколы изменяют только содержимое файла, но не влияют на его размер и скорость прохождения. В связи с этим можно без каких-либо трудностей отлавливать передаваемые пакеты читать их или заменять другими.
Второй способ для обеспечения защиты API скрипта это ввод системы ключевого доступа. Суть данной системы состоит в том, чтобы запретить доступ к самому скрипту разработчикам, не зарегистрированным на сайте и не прошедшим одобрение. Такая система работает на большинстве API скриптов, в частности платежный агрегатор Free-kassa использует такой уровень доступа. Зарегестрированному разработчику выдается специальный набор ключей и паролей которые он передает в API скрипт вместе со своим запросом на сервер. Сервер проверив подлинность ключей и в случае положительного значения выдает результат.
Формирование подписи в платежной форме
ГРодписи дчя плате фермы форчжрустся путем нянэвдрния MDS-xcmks от строки ID вашига магазин а Сумм a г г л й те- ж а: С © к р е т н ü е слаоо:Н&мер заказа’ гтример из Г’НР
■irf Г » 7+IJ : 300 , J. s : imi ff* : 3 Н ‘ I
Пример платёжной формы: ■ ipftp
Slip — uSS-i. Swci111 .fordcr _HKSiint. 1 fs^crcijemd.’ 5эгФег_1,1 .
■ input type* »«idd*:- пдвд ■ ‘■ 1 ‘»plw1 ? ■:input type- ‘Uder ние- J ‘ .jZjC-‘L
mpyt typ*» «idr)erJ пяг^-‘liinj vpjyer’ni’ ■
■ input type-‘ ‘ iddflr ■ liaire- uE_ißfih’ vlS-uE-1 i^dhp-idaSirl’lCiglfl1 JiV* ■«input tjfpe^’ s(ilr«Lt ‘ П0*4’~;р*у’ v«3ue4Li,ilnn«Tii.T»,i.
Рисунок 2. Формирование подписи (Ключа)
На рисунке 2 показан пример формирования подписи для API ключа Free-kassa который составляется из номера заказа, имени аккаунт, уникального индентификатора магазина и секретного пороля. Весь пароль хешируется специальным способом MD5.
MD5 (Message Digest 5) — 128-битный алгоритм хеширования, разработанный профессором Рональдом Л. Ривестом из Массачусетского технологического института в 1991 году. Предназначен для создания «отпечатков» или дайджестов сообщения произвольной длины и последующей проверки их подлинности. Широко применялся для проверки целостности информации и хранения хешей паролей [5].
Третьим способом защиты данных является разграничение прав доступа. Данное разграничение не имеет смысла для простых скриптов, но в нашем случае его стоит рассмотреть так как у нас хранится персональная информация, которая должна быть доступна по запросу с API скрипта. Данный способ подразумевает наличие отдельного хеш ключа который будет открывать доступ приложению к персональным данным пользователя в случае получения API скриптом логина и пароля пользователя. Данный способ широко используется в API скриптах таких сайт как вконтакте, mail.ru и многих других социальных сетях.
Использование API скриптов является одним из самых простых и быстрых возможностей реализации взаимодействия между различными проектами. И при соблюдении достаточных мер безопасности достаточно надежным.
1. WINDOWS API [Электронный ресурс] URL: http://system-repair.net (дата обращения: 01.01.2019).
2. POST и GET [Электронный ресурс] URL: http://php.net/ (дата обращения:
3. Введение в JSON [Электронный ресурс] URL: http://json.org/ (дата обращения: 01.01.2019).
4. HTTPS | MDN [Электронный ресурс] URL: https://developer.mozilla.org (дата обращения: 01.01.2019).
5. Функции обработки строк [Электронный ресурс] URL: http://www.php.su (дата обращения: 01.01.2019).
Палаш Б.В. студент 2 курса
Хакасский государственный университет им. Н. Ф. Катанова
научный руководитель: Голубничий А.А.
Россия, г. Абакан ОСНОВНЫЕ ПРИНЦИПЫ РАБОТЫ АЛГОРИТМА РАСПРЕДЕЛЕНИЯ СТУДЕНТОВ ПО НАУЧНЫМ РУКОВОДИТЕЛЯМ В СРЕДНИХ И ВЫСШИХ УЧЕБНЫХ
Аннотация: В статье описываются основные принципы работы алгоритма распределения студентов по научным руководителям для средних и высших учебных заведений.
Ключевые слова: Образование, Алгоритмы
Palash B. V. student
Katanov Khakass State University Russia, Abakan Scientific supervisor: Golubnichiy A.A. BASIC PRINCIPLES OF OPERATION OF ALGORITHM OF DISTRIBUTION OF STUDENTS BY ACADEMIC SUPERVISORS IN SECONDARY AND HIGHER EDUCATIONAL INSTITUTIONS Abstract: This article describes the basic principles of the algorithm of distribution of students by supervisors for secondary and higher educational institutions.
Key words: Education, Algorithm
Каждые полгода любой институт или колледж сталкивается с необходимостью распределения студентов среди научных руководителей для индивидуальной работы по выполнению выпускной квалификационной работы или курсовых проектов. Часто возникают различные споры и недовольства распределительной системой. Некоторые институты распределяют студентов по научным руководителям без обсуждения с обучающимися, самостоятельно. Это иногда приводит к тому, что студенты попадают к научному руководителю, не обладающему достаточными
Введение в web APIs
Начнём с рассмотрения того что представляют собой API на высоком уровне и выясним, как они работают, как их использовать в своих программах и как они структурированы. Также рассмотрим основные виды API и их применение.
Необходимые знания: | Базовая компьютерная грамотность, понимание основ HTML и CSS, основы JavaScript (см. первые шаги, building blocks, объекты JavaScript). |
---|---|
Цель: | Познакомиться с API, выяснить что они могут делать и как их использовать. |
Что такое API?
Интерфейс прикладного программирования (Application Programming Interfaces, APIs) — это готовые конструкции языка программирования, позволяющие разработчику строить сложную функциональность с меньшими усилиями. Они «скрывают» более сложный код от программиста, обеспечивая простоту использования.
Для лучшего понимания рассмотрим аналогию с домашними электросетями. Когда вы хотите использовать какой-то электроприбор, вы просто подключаете его к розетке, и всё работает. Вы не пытаетесь подключить провода напрямую к источнику тока — делать это бесполезно и, если вы не электрик, сложно и опасно.
Точно также, если мы хотим, например, программировать 3D графику, гораздо легче сделать это с использованием API, написанных на языках высокого уровня, таких как JavaScript или Python.
Примечание: Смотрите также API в словаре.
API клиентской части JavaScript
Для JavaScript на стороне клиента, в частности, существует множество API. Они не являются частью языка, а построены с помощью встроенных функций JavaScript для того, чтобы увеличить ваши возможности при написании кода. Их можно разделить на две категории:
- API браузера встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, Web Audio API предоставляет конструкции JavaScript для работы с аудио в браузере, например,можно взять звуковую дорожку, изменить её громкость или применить к ней эффекты. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++ или Rust) для обработки звука, но, как было сказано выше, эти детали скрыты благодаря API.
- Сторонние API не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в интернете. Например, Twitter API позволяет размещать последние твиты (tweets) на вашем веб-сайте. В данном API определён набор конструкций, осуществляющих запросы к сервисам Twitter и возвращающих определённые данные.
Взаимодействие JavaScript, API и других средств JavaScript
Итак, выше мы поговорили о том, что такое JavaScript API клиентской части и как они связаны с языком JavaScript. Давайте теперь тезисно запишем основные понятия и определим назначение других инструментов JavaScript:
- JavaScript — Язык программирования сценариев высокого уровня, встроенный в браузер, позволяющий создавать функциональность веб-страниц/приложений. Отметим, что JavaScript также доступен на других программных платформах, таких как Node.js. Но пока не будем останавливаться на этом.
- API браузера (Browser APIs) — конструкции, встроенные в браузер, построенные на основе языка JavaScript, предназначенные для облегчения разработки функциональности.
- Сторонние API (Third party APIs) — конструкции, встроенные в сторонние платформы (такие как Twitter, Facebook) позволяющие вам использовать часть функциональности этих платформ в своих собственных веб-страницах/приложениях (например, показывать последние Твиты на вашей странице).
- Библиотеки JavaScript — Обычно один или несколько файлов, содержащих пользовательские (custom) функции. Такие файлы можно прикрепить к веб-странице, чтобы ускорить или предоставить инструменты для написания общего функциональности. Примеры: jQuery, Mootools и React.
- JavaScript фреймворки (frameworks) — cледующий шаг в развитии разработки после библиотек. Фреймворки JavaScript (такие как Angular и Ember) стремятся к тому, чтобы быть набором HTML, CSS, JavaScript и других технологий, после установки которого можно «писать» веб-приложение с нуля. Главное различие между фреймворками и библиотеками — «обратное направление управления» ( «Inversion of Control» ). Вызов метода из библиотеки происходит по требованию разработчика. При использовании фреймворка — наоборот, фреймворк производит вызов кода разработчика.
На что способны API?
Широкое разнообразие API в современных браузерах позволяет наделить ваше приложение большими возможностями. Достаточно посмотреть список на странице MDN APIs index page.
Распространённые API браузера
В частности, к наиболее часто используемым категориям API (и которые мы рассмотрим далее в этом модуле) относятся :
- API для работы с документами, загруженными в браузер. Явный пример — DOM (Document Object Model) API, позволяющий работать с HTML и CSS — создавать, удалять и изменять HTML, динамически изменять вид страницы и т.д. Любое всплывающее окно на странице или появляющееся «на ходу» содержимое — всё это благодаря DOM. Узнайте больше об этой категории API на странице Работа с документами.
- API, принимающие данные от сервера, часто используются, чтобы обновить небольшие части веб-страницы. Эта, казалось бы, малая деталь оказывает огромное влияние на производительность и поведение сайтов, так как нет необходимости перезагружать всю страницу целиком, если вам нужно просто обновить список товаров или новых доступных историй. Это также сделает приложение или сайт более отзывчивым и «живым». Список API, благодаря которым это возможно, включает: XMLHttpRequest и Fetch API. Вы также могли встретить термин Ajax, описывающий эту технологию. Узнать больше об этой категории API на странице Получение данных от сервера.
- API для работы с графикой широко поддерживаются браузерами, самые популярные: Canvas и WebGL, позволяющие программно изменять данные о пикселях, содержащиеся в элементе HTML для создания 2D и 3D изображений. Например, вы можете нарисовать фигуры, скажем, прямоугольники или круги, импортировать изображение в canvas и применить к нему фильтры, такие как сепия или оттенки серого с помощью Canvas API, или создать сложное 3D-изображение с освещением и текстурами, используя WebGL. Такие API часто используют в сочетании с API создания анимационных циклов (таких как window.requestAnimationFrame() ) и другими для создания постоянно меняющегося изображения на экране, как в мультфильмах или играх .
- Аудио и Видео API как HTMLMediaElement , Web Audio API, и WebRTC позволяют делать действительно интересные вещи с мультимедиа. Например, создать собственный пользовательский интерфейс (User Interface, UI) для проигрывания аудио/видео, вывод на экран субтитров, записывать видео с веб-камеры для обработки в canvas (см. выше) или для передачи на другой компьютер в видео-конференции, применять звуковые эффекты к аудио-файлам (такие как gain, distortion, panning и т.д.).
- API устройств — в основном, это API для обработки и считывания данных с современных устройств удобным для работы веб-приложений образом. Например, Geolocation API позволяет считать данные о местоположении устройства. Другие примеры включают уведомление пользователя о появившемся обновлении для веб-приложения с помощью системных уведомлений (см. Notifications API) или вибрации (см. Vibration API (en-US)).
- API хранения данных на стороне пользователя приобретают всё большее распространение в веб-браузерах — возможность хранить информацию на стороне клиента очень полезна, когда необходимо создать приложение, которое будет сохранять своё состояние между перезагрузками страницы, или даже работать, когда устройство не в сети. В данный момент доступно немало таких API. Например, простое хранилище данных в формате имя/значение (name/value) Web Storage API или хранилище данных в формате таблиц IndexedDB API.
Распространённые сторонние API
Существует множество сторонних API; некоторые из наиболее популярных, которые вы рано или поздно будете использовать, включают:
- Twitter API для добавления такой функциональности, как показ последних твитов на сайте.
- Google Maps API для работы с картами на веб-странице (интересно, что Google Maps также использует этот API). Теперь это целый набор API, который может справляться с широким спектром задач, как свидетельствует Google Maps API Picker.
- Набор Facebook API позволяет использовать различные части платформы Facebook в вашем приложении, предоставляя, например, возможность входа в систему с логином Facebook, оплаты покупок в приложении, демонстрация целевой рекламы и т.д.
- YouTube API, предоставляющий возможность встраивать видео с YouTube на вашем сайте, производить поиск, создавать плейлисты и т.д.
- Twilio API — фреймворк для встраивания функциональности голосовой и видео связи в вашем приложении, отправки SMS/MMS из приложения и т.д.
Примечание: вы можете найти информацию о гораздо большем количестве сторонних API в Каталоге Web API.
Как работает API?
Работа разных JavaScript API немного отличается, но, в основном, у них похожие функции и принцип работы.
Они основаны на объектах
Взаимодействие с API в коде происходит через один или больше объектов JavaScript, которые служат контейнерами для информации, с которой работает API (содержится в свойствах объекта), и реализуют функциональность, которую предоставляет API (содержится в методах объекта).
Примечание: Если вам ещё не известно как работают объекты, советуем вернуться назад и изучить модуль Основы объектов JavaScript прежде чем продолжать.
Вернёмся к примеру с Web Audio API — это довольно сложный API, состоящий из ряда объектов. Наиболее очевидные из них
- AudioContext , представляющий аудиограф (en-US), который содержит ряд полезных свойств и методов для управления воспроизведением звука в браузере.
- MediaElementAudioSourceNode представляет элемент , включающий в себя звук, которым можно управлять внутри аудиоконтекста или воспроизвести.
- AudioDestinationNode (en-US) представляет место назначения звука, то есть устройство вашего компьютера, которые фактически выводит его. Обычно это динамики или наушники.
Так как же эти объекты взаимодействуют? Если вы посмотрите на наш пример simple web audio example (see it live also), вы увидите следующий код:
audio src="outfoxing.mp3">audio> button class="paused">Playbutton> br /> input type="range" min="0" max="1" step="0.01" value="1" class="volume" />
Прежде всего, добавляем элемент audio , с помощью которого встраиваем MP3 на страницу. Мы не включаем какие-либо элементы управления по умолчанию. Далее добавляем элемент , который будем использовать для воспроизведения и остановки музыки, и элемент с типом range, он понадобится для регулировки громкости трека во время его воспроизведения.
Взглянем на JavaScript код этого примера.
Начнём с того, что создадим экземпляр конструктора AudioContext , с помощью которого будет манипулировать нашим треком.
const AudioContext = window.AudioContext || window.webkitAudioContext; const audioCtx = new AudioContext();
Далее создадим константы для наших , и элементов и воспользуемся методом AudioContext.createMediaElementSource() для создания MediaElementAudioSourceNode , представляющий источник аудио, с которым будет воспроизводиться элемент audio .
const audioElement = document.querySelector("audio"); const playBtn = document.querySelector("button"); const volumeSlider = document.querySelector(".volume"); const audioSource = audioCtx.createMediaElementSource(audioElement);
Затем включим пару обработчиков событий для переключения между воспроизведением и паузой при нажании на кнопку и сброса воспроизведения в начало, когда песня закончится:
.addEventListener("click", () => // проверить, находится ли контекст в приостановленном состоянии if (audioCtx.state === "suspended") audioCtx.resume(); > // если трек остановлен, то начать его проигрывать if (playBtn.getAttribute("class") === "paused") audioElement.play(); playBtn.setAttribute("class", "playing"); playBtn.textContent = "Pause"; // если трек воспроизводится, приостановить проигрывание > else if (playBtn.getAttribute("class") === "playing") audioElement.pause(); playBtn.setAttribute("class", "paused"); playBtn.textContent = "Play"; > >); // если трек закончился audioElement.addEventListener("ended", () => playBtn.setAttribute("class", "paused"); playBtn.textContent = "Play"; >);
Примечание: обратите внимание, что методы play() и pause() , используемые для воспроизведения и приостановки дорожки, не являются частью Web Audio API. Они являются частью HTMLMediaElement API, который отличается от Web Audio API, но тесно с ним связан.
Далее создадим объект GainNode (en-US) с помощью метода AudioContext.createGain() (en-US), который можно использовать для регулировки громкости звука, и еще один обработчик событий, с помощью которого будем менять значение усиления (громкости) в зависимости от значения .
// volume const gainNode = audioCtx.createGain(); volumeSlider.addEventListener("input", () => gainNode.gain.value = volumeSlider.value; >);
Наконец, чтобы всё заработало, соединим различные узлы в аудиографе с помощью метода AudioNode.connect() (en-US), доступном на каждом узле этого типа:
.connect(gainNode).connect(audioCtx.destination);
Звук начинается в источнике, который затем подключаетя к узлу усиления, чтобы можно было регулировать громкость звука. Затем узел усиления подключается к узлу назначения звука, чтобы его можно было воспроизвести на компьютере (по умолчанию свойство AudioContext.destination (en-US) равно значению AudioDestinationNode , которое имеет доступ к аудио-оборудованию компьютера, например, к динамикам).
У них узнаваемые точки входа
При использовании API убедитесь, что вы знаете где точка входа для API. В Web Audio API это довольно просто — экземпляр констуктора AudioContext , возвращает объект, внутри которого доступны все полезные методы и свойства для манипуляции звуком.
Найти точку входа Document Object Model (DOM) API ещё проще — при применении этого API используется объект Document , или экземпляр элемента HTML, с которым вы хотите каким-либо образом взаимодействовать, к примеру:
const em = document.createElement("em"); // создаёт новый элемент em const para = document.querySelector("p"); // ссылка на существующий элемент p em.textContent = "Hello there!"; // присвоение текстового содержимого para.appendChild(em); // встроить em внутрь para
Точки входа других API немного сложнее, часто подразумевается создание особого контекста, в котором будет написан код API. Например, объект контекста Canvas API создаётся получением ссылки на элемент , на котором вы хотите рисовать. Затем необходимо вызвать метод HTMLCanvasElement.getContext() :
const canvas = document.querySelector("canvas"); const ctx = canvas.getContext("2d");
Всё, что мы хотим сделать с canvas после этого, достигается вызовом свойств и методов объекта содержимого (content) (который является экземпляром CanvasRenderingContext2D ), например:
Ball.prototype.draw = function () ctx.beginPath(); ctx.fillStyle = this.color; ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI); ctx.fill(); >;
Примечание: вы можете увидеть этот код в действии в нашем bouncing balls demo (see it running live also).
Они используют события для управления состоянием
Мы уже обсуждали события ранее в этом курсе, в нашей статье Введение в события — в ней детально описываются события на стороне клиента и их применение. Если вы ещё не знакомы с тем, как работают события клиентской части, рекомендуем прочитать эту статью прежде, чем продолжить.
В некоторых API содержится ряд различных событий, в некоторых — событий нет. Свойства обработчика, позволяющие запускать функции при совершении какого-либо события по большей части перечислены в нашем материале отдельного раздела «Обработчики событий (Event handlers)».
Мы уже видели несколько обработчиков событий, используемых в нашем примере с Web Audio API выше:
// play/pause audio playBtn.addEventListener("click", () => // check if context is in suspended state (autoplay policy) if (audioCtx.state === "suspended") audioCtx.resume(); > // if track is stopped, play it if (playBtn.getAttribute("class") === "paused") audioElement.play(); playBtn.setAttribute("class", "playing"); playBtn.textContent = "Pause"; // if track is playing, stop it > else if (playBtn.getAttribute("class") === "playing") audioElement.pause(); playBtn.setAttribute("class", "paused"); playBtn.textContent = "Play"; > >); // if track ends audioElement.addEventListener("ended", () => playBtn.setAttribute("class", "paused"); playBtn.textContent = "Play"; >);
У них есть дополнительные средства безопасности там, где это необходимо
Функциональность WebAPI подвержена тем же соображениям безопасности, что и JavaScript или другие веб-технологии (например, same-origin policy), но иногда они содержат дополнительные механизмы защиты. К примеру, некоторые из наиболее современных WebAPI работают только со страницами, обслуживаемыми через HTTPS в связи с передачей конфиденциальных данных (примеры: Service Workers и Push).
К тому же, некоторые WebAPI запрашивают разрешение от пользователя, как только к ним происходит вызов в коде. Например, Notifications API запрашивает разрешение для показа диалогого окна:
Web Audio и HTMLMediaElement API подчиняются механизму безопасности, который называется политикой автозапуска (en-US) . Это означает, что вы не можете автоматически воспроизводить звук при загрузки страницы — вы должны разрешить своим пользователям инициировать воспроизведения звука с помощью какого-либо элемента управления, например, кнопки. Сделано это, потому что автовоспроизведение звука обычно очень раздражает, и мы не должны подвергать этому наших пользователей.
Итоги
На данном этапе, у вас должно сформироваться представление о том, что такое API, как они работают и как вы можете применить их в своём JavaScript-коде. Вам наверняка не терпится начать делать по-настоящему интересные вещи с конкретными API, так вперёд! В следующий раз мы рассмотрим работу с документом с помощью Document Object Model (DOM).
В этом модуле
- Введение в web APIs
- Manipulating documents
- Fetching data from the server
- Third party APIs
- Drawing graphics (en-US)
- Video and audio APIs (en-US)
- Client-side storage
Found a content problem with this page?
- Edit the page on GitHub.
- Report the content issue.
- View the source on GitHub.
This page was last modified on 7 сент. 2023 г. by MDN contributors.
REST API: хэширование, работа со скриптами и отправка вспомогательных запросов¶
Для хэширования, работы со скриптами и отправки вспомогательных запросов к ноде предусмотрена группа методов utils :
Хэширование: utils/hash ¶
POST /utils/hash/fast¶
Метод возвращает хэш-сумму строки, переданной в запросе.
Пример ответа:
"message": "ridethewaves!", "hash": "DJ35ymschUFDmqCnDJewjcnVExVkWgX7mJDXhFy9X8oQ" >
POST /utils/hash/secure¶
Метод возвращает двойную хэш-сумму строки, переданной в запросе.
Пример ответа:
"message": "ridethewaves!", "hash": "H6nsiifwYKYEx6YzYD7woP1XCn72RVvx6tC1zjjLXqsu" >
Работа со скриптами: utils/script ¶
Данная группа методов предназначена для конвертации кода скриптов в формат base64 и их декодирования. Скрипты привязываются к аккаунтам при помощи транзакций 13 (привязка скрипта к адресу) и 15 (привязка скрипта к ассету для адреса).
POST /utils/script/compile¶
Метод конвертирует код скрипта в формат base64.
Пример запроса: