Api

Организация курса

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

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

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

Спецификация OpenAPI и SwaggerСпецификация OpenAPI предоставляет один из способов описания REST API и включает все разделы, упомянутые в модуле Документирование конечных точек API. Фреймворки, такие как Swagger UI, могут анализировать спецификацию OpenAPI и генерировать интерактивную документацию, которая позволяет пользователям опробовать конечные точки при изучении API.

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

Однако простая игра в редакционную/издательскую функцию может сделать из вас простого секретаря.

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

Вы можете оценить качество документации API, посмотрев, включает ли она эти не справочные темы.

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

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

Нативные библиотеки APIAPI нативных библиотек относятся к Java, C ++ или другим API, специфичным для программирования. При таком подходе вместо запроса информации через Интернет, библиотека кода загружается и интегрируется в проект. Библиотека компилируется непосредственно в сборку приложения (а не доступна через веб-протоколы, как с REST API). Хотя такой тип API встречается реже, он включен здесь частично, для пояснения, что отличает API REST от API нативных библиотек.

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

Что значит API?

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

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

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

Главный принцип работы API. Почему его называют интерфейсом

Простыми словами, интерфейс – это «прослойка» между приложением А и приложением Б. В ней происходят процессы, которые позволяют двум программам обмениваться информацией и выполнять функции, связанные с обеими сторонами, скрывая «внутреннее строение» программ. Знакомо? Только что таким же образом мы описали API.

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

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

Отсутствие результата — тоже результат

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

Плохо

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

Хорошо:

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

Это дополнение к . Работа ведётся на Github. Англоязычный вариант этой же главы опубликован на medium. Я буду признателен, если вы пошарите его на реддит — я сам не могу согласно политике платформы.

Стратегии документирования вложенных объектов

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

Очень популярно использование таблиц. В курсе Петера Грюнбаума по технической документацииAPI для Udemy Грюнбаум представляет вложенные объекты, используя таблицы с различными столбцами:

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

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

Другие API будут вкладывать определения ответов для имитации структуры JSON. Вот пример из bit.ly API:

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

Подход eBay еще уникальнее. В их случае вложен в , который вложен в , который вложен в

(Обратите внимание, что этот ответ находится в формате XML вместо JSON.):

Вот документация ответа:

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

Кнопка Run in Postman

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

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

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

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

сеть API Postman

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

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

Вариант открытия коллекции

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

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

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

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

Dart на сервере

Tutorial

Недавно столкнулся с необходимостью написать REST API сервер на Dart. Оставим за рамками этой статьи почему и зачем это было надо, но первое с чем я столкнулся — выбор библиотек. Так уж сложилось, что я привык писать на NodeJS используя KoaJS в качестве веб сервера. Простая и удобная библиотека с кучей расширений для любой необходимости. А вот Dart в этом плане несколько подкачал. На момент поисков из «живых» пакетов на pub.dev был только shelf. Что-то отдаленно похожее, но по факту жутко неудобное. Неделю промучившись с оным, понял, надо писать свое, с блэкджеком… что-нибудь в стиле того же KoaJS.

Интерактивное голосовое редактирование текста с помощью новых речевых технологий от Яндекса

Сегодня наше приложение Диктовка для интерактивного написания и редактирования текста голосом появилось в AppStore и Google Play. Его главная задача — продемонстрировать часть новых возможностей комплекса речевых технологий Яндекса. Именно о том, чем интересны и уникальны наши технологии распознавания и синтеза речи, я хочу рассказать в этом посте.
Пара слов, чтобы вы понимали, о чём пойдёт речь. Яндекс уже давно предоставляет бесплатное мобильное API, которое можно использовать, например, для распознавания адресов и голосовых запросов к поиску. За этот год мы смогли довести его качество почти до того же уровня, на котором такие запросы и реплики понимают сами люди. И теперь мы делаем следующий шаг — модель для распознавания свободной речи на любую тему.
Кроме этого, наш синтез речи поддерживает эмоции в голосе. И, насколько нам известно, это пока первый коммерчески доступный синтез речи с такой возможностью.
Обо всём этом, а также о некоторых других возможностях SpeechKit: об активации голосом, автоматической расстановке пунктуационных знаков и распознавании смысловых объектов в тексте — читайте ниже.

Избегайте двойных отрицаний

Плохо: — люди в целом плохо считывают двойные отрицания. Это провоцирует ошибки.

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

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

Условие «кофе можно приготовить» будет выглядеть как — есть и зерно, и стакан. Однако, если по какой-то причине в ответе будут отрицания тех же флагов:

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

Весь веб на 60+ FPS: как новый рендерер в Firefox избавился от рывков и подтормаживаний

Перевод

До релиза Firefox Quantum остаётся всё меньше времени. Он принесёт множество улучшений в производительности, в том числе сверхбыстрый движок CSS, который мы позаимствовали у Servo.
Но есть ещё одна большая часть технологии Servo, которая пока не вошла в состав Firefox Quantum, но скоро войдёт. Это WebRender, часть проекта Quantum Render.
WebRender известен своей исключительной скоростью. Но главная задача — не ускорить рендеринг, а сделать его более плавным.
При разработке WebRender мы поставили задачу, чтобы все приложения работали на 60 кадрах в секунду (FPS) или лучше, независимо от размера дисплея или от размера анимации. И это сработало. Страницы, которые пыхтят на 15 FPS в Chrome или нынешнем Firefox, летают на 60 FPS при запуске WebRender.
Как WebRender делает это? Он фундаментальным образом меняет принцип работы движка рендеринга, делая его более похожим на движок 3D-игры.

Тяжкое наследие прошлого. Проблемы командной строки Windows

Перевод

Предисловие от автора, Рича Тёрнера из Microsoft. Это статья о командной строке: от её появления и эволюции до планов капитального ремонта Windows Console и командной строки в будущих версиях Windows. Будь вы опытным профессионалом или новичком в IT, надеемся, что вы найдёте статью интересной.

Давным-давно в далёкой-далёкой серверной…

С первых дней развития информатики людям нужен был эффективный способ передавать компьютеру команды и данные и видеть результат выполнения этих команд/вычислений.
Одним из первых по-настоящему эффективных человеко-машинных интерфейсов стал Tele-Typewriter или «телетайп». Это электромеханическая машина с клавиатурой для ввода данных и каким-нибудь устройством вывода — сначала использовался принтер, позже экран.

Пример и схема ответа конечной точки SurfReport

Давайте создадим раздел для нашей конечной точки , в котором покажем пример и схему ответа.

Вот пример к разделу:

Пример ответа

Ниже пример ответа конечной точки

В таблице ниже описание для каждого пункта

Избегайте частичных обновлений

Плохо:

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

Во-первых, экономия объёма ответа в современных условиях требуется редко. Максимальные размеры сетевых пакетов (MTU, Maximum Transmission Unit) в настоящее время составляют более килобайта; пытаться экономить на размере ответа, пока он не превышает килобайт — попросту бессмысленная трата времени.

Перерасход трафика возникает, если:

• не предусмотрен постраничный перебор данных;

• не предусмотрены ограничения на размер значений полей;

• передаются бинарные данные (графика, аудио, видео и т.д.).

Во всех трёх случаях передача части полей в лучше случае замаскирует проблему, но не решит. Более оправдан следующий подход:

• для «тяжёлых» данных сделать отдельные эндпойнты;

• ввести пагинацию и лимитирование значений полей;

• на всём остальном не пытаться экономить.

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

В-третьих, этот подход может как-то работать при необходимость перезаписать поле. Но что делать, если поле требуется сбросить к значению по умолчанию? Например, как удалить ?

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

Хорошо: можно применить одну из двух стратегий.

Вариант 1: разделение эндпойнтов. Редактируемые поля группируются и выносятся в отдельный эндпойнт. Этот подход также хорошо согласуется , который мы рассматривали в предыдущем разделе.

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

Вариант 2: разработать формат описания атомарных изменений.

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

Проблема документирования API

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

1. Сложность написания документации API, так как это очень трудная тема. Неясно как писать, что писать и прочее. При написании возникает очень много вопросов. Тем более, если человек до этого никогда не имел дело с документированием API.
2. Поддержка документации API в актуальном состоянии.

Проблема стандартизации API

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

1. Пример полного запроса.
2. Примеры ожидаемого ответа.
3. Список кодов ошибок.
4. Удобный для поиска Web–интерфейс.
5. Предупреждения об изменении версии и расписание устаревания.

Способы создания документации API

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

Повторюсь, ведь от актуальности документации API зависит качество разработки ПО.

Одни из самых популярных спецификаций — это RAML, Swagger и API Blueprint.
Например, если программирование Системы происходи в MS Visual Studio, то в ней автоматически генерируется Xml (представлена на картинке ниже), с помощью которой уже можно создать в любой другой спецификации документацию API.

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

Graphql

Tutorial

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

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

Для использования GraphQL, установим пакет graphql с помощью команд:yarn add graphql, если используете менеджер пакетов yarn npm i graphql —save, для менеджера пакетов npm

API — что это такое, зачем они нужны и что умеют?

По сути, если бы не было API, не было бы Windows, поскольку всё это множество программ взаимодействует между собой, использует ресурсы операционной системы и «железа», именно с помощью API.

API выполняет связующую функцию

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

API-интерфейсы экономят время программистов

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

API позволяют обеспечить обмен информацией

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

Крупные издания, к примеру, The New York Times, именно с помощью API предоставляют доступ  к своей базе данных, в которой хранится не одна тысяча статей.

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

API используются для контроля доступа к программным и аппаратным ресурсам

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

API позволяют поддерживать сотрудничество

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

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

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