Что такое api?

Краткое введение в RAML

Вводная часть

• версия RAML;
• имя документа;
• URI, по которому доступен API;
• версия API, описываемая в документации.

#% RAML 0.8
title: Example API
baseUri: http://api.example.com/{version}
version: v1

protocols: 

documentation
    - title: Home
        content: |
                  API Test Documentation

Схемы безопасности

#%RAML 0.8
title: Example API
version: 1
baseUri: https://api.example.com/{version}
securedBy: 
securitySchemes:
    - oauth_2_0:
               type: OAuth 2.0
        describedBy:
            headers:
                Authorization:
                         type: string
            queryParameters:
                access_token:
                      type: string
            responses:
                401:
                    description: |
                        Bad or expired token.                 
                 403:
                    description: |
                        Bad OAuth request 
        settings:
          authorizationUri:  https://example.com/oauth/authorize         
          accessTokenUri: https://example.com/oauth/token
          authorizationGrants: 

• в параметре type указывается, что в API используется авторизация по протоколу OAuth2;
• далее указывается, что авторизационные данные можно передавать либо в заголовке Authorization, либо в query-параметре access_token;
• после этого следуют возможные коды ответов и их описания;
• в конце раздела, в секции settings указываются URL для авторизации, URL для получения токена, а также необходимые для аутентификации параметры (authorization grants).

#%RAML 0.8
title: Example API
version: 1
baseUri: https://api.example.com/{version}
securedBy: 
securitySchemes:
    - oauth_2_0: !include oauth_2_0.yml

Объекты и методы

/document
 get:
 put:
 post:
  /{documentId}
   get:
   delete:

/documents
   get
     headers:
        X-Auth-Token:
        required: true

/document
      /{documentId}
              uriParameters:
                       id:
                        description: document identification number
                        type: string
                        pattern: ^{2}\-{3}\-\d{2}\-\d{5}$

/documents
   get:
        description: Retrieve a list of documents
   post:
         description: Add a new document
   body: 
          application/x-www-form-urlencoded
                 formParameters:  
                         id: 
                           description: document identification number
                           type: string
                           pattern: {2}\-{3}\-\d{2}\-\d{5}$
                         name:
                             description: the name of the document
                             type: string
                             required: true
                          author: 
                                description: The name of the author
                                type: string
                                 required: true

/documents
  get
      

Query-параметры

 /document:
     get:
       queryParameters:
         author:
           displayName: Author
           type: string
           description: The author's full name
           example: Ivan Petrov
           required: false
         name:
           displayName: Document Name
           type: string
           description: The name of the document
           example: Delivery contract
           required: false
         signingDate:
           displayName: signingDate
           type: date 
           description: The date when the document was signed
           example: 2015-07-15
           required: false

Профили

#% RAML 0.8
title: Example API
baseUri: http://api.example.com/{version}
version: v1

traits:
 - searchable:
    queryParameters:
         author:
           displayName: Author
           type: string
           description: The author's full name
           example: Ivan Petrov
           required: false
         name:
           displayName: Document Name
           type: string
           description: The name of the document
           example: Delivery contract
           required: false
         signingDate:
           displayName: signingDate
           type: date 
           description: The date when the document was signed
           example: 2015-07-15
           required: false

/document:
     get:
            is: 

Описание ответа

 /documents:
   /{documentId}:
     get:
       description: Retrieve document information
       responses:
         200:
          body:
           application/json:
             schema |
               {"$schema": “http://json-schema.org/schema”,
                "type":"object"
                "description": "a document"
                "properties": {
                     "id":{"type":"string"}
                     "name":{"type":"string"}
                     "author":{"type":"string"}
                     "signingDate": {"type":"date"}
               example: |
               {"data:" {
                  "id": "DOC3456"
                  "name": "New Delivery Contract"
                  "author": "Ivan Petrov"
                  "signingDate": "2015-05-20"
                },
                "success": true
                "status": 200
              } 

schemas:
 - !include document-schema.yaml

/articles:
 get:
  responses:
   200:
    body:
     application/json:
      schema: document

Введение

Вы наверное безумец, если не согласны со следующим утверждением:

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

Однако, вам кажется, что вы не совсем понимаете что это такое.

Возможно, вам хотелось бы знать, какие приложения используются для API, как ими пользоваться, и как они будут влиять на работу аффилиатов в будущем?

Не беспокойтесь! Эта статья – то, чего вы так долго ждали!

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

К концу прочтения статьи вы будете знатоком этой темы!

Хватит вступлений. Начнем, пожалуй!

Последовательность и действия

Необязательно изучать модули по порядку — можно “гулять” по ним по своему усмотрению. Но некоторые из модулей (например, Используем REST API в роли разработчика и Конечные точки API) желательно пройти последовательно.

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

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

Практические занятия помечаются иконкой в заголовке раздела:

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

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

# Какие дополнительные методы API нужно использовать при доставке товаров с 15 марта (FBS)

Изменения вступают в силу с 15 марта 2021 года.

Порядок использования дополнительных методов API распространяется только на FBS.

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

Ozon Логистика

• Если у вас больше одного склада со способом доставки Ozon Логистика, то вам нужно печатать акт приёма-передачи на каждый метод на складах.
  Специально изменять статусы отправлений, получать данные или добавлять трек-номер через API вам не нужно, это будет делать Ozon.
  Используйте для печати актов методы API:
  • — выводит список складов.
  • — выводит список методов по каждому складу.
  • — формирует акт приёма-передачи для каждого метода на каждом складе.

Другая служба доставки или самостоятельно

• Для интегрированной, неинтегрированной или собственной службы доставки потребуется информация об отправлениях. Например, Ф.И.О. получателя и его контактные данные:

• Для интегрированной службы доставки вам нужно добавлять трек-номер к каждому отправлению. По трек-номеру Ozon будет отслеживать статус отправлений и показывать их в вашем личном кабинете и личном кабинете покупателя:

  POST /v2/fbs/posting/tracking-number/set — добавляет трек-номер к отправлению.

• Для неинтегрированной или своей службы доставки вам нужно изменять статусы отправлений у каждого заказа:

  • — изменяет статус на Доставляется.
  • — изменяет статус на Курьер в пути.
  • — изменяет статус на Доставлен.

• Если в вашем личном кабинете заведено больше одного склада, то вам нужно обновлять на них остатки:

  • — выводит список складов.
  • — обновляет количество товаров на складе.

Использование в рекламе

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

Например, API «Яндекс.Директа»: с его помощью можно гибко настраивать рекламные кампании, просматривать статистику, создавать приложения, работающие с контекстной рекламой самостоятельно.

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

Каковы преимущества использования API?

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

Публичные и партнерские API дают организациям:

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

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

Типы API

Существует четыре основных типа API-интерфейсов: частные, общедоступные, партнерские и составные.

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

API могут быть дополнительно классифицированы как локальные, веб-интерфейсы или программные API.

• Локальные API предлагают сервисы ОС или промежуточного программного обеспечения для прикладных программ. API Microsoft .NET, TAPI (Telephony API) для голосовых приложений и API доступа к базе данных являются примерами локальной формы API.
• Веб-API предназначены для представления широко используемых ресурсов, таких как HTML-страницы, и доступ к ним осуществляется с помощью простого протокола HTTP. Любой веб-URL активирует веб-API. Веб-API часто называют RESTful, потому что издатель интерфейсов REST не сохраняет никаких данных внутри между запросами. Таким образом, запросы от многих пользователей могут смешиваться, как если бы они были в Интернете.
• Программные API основаны на технологии удаленного вызова процедур (RPC), которая заставляет удаленный программный компонент казаться локальным для остальной части программного обеспечения. API-интерфейсы сервис-ориентированной архитектуры (SOA), такие как API-интерфейсы Microsoft WS, являются программными API-интерфейсами.

Примеры API

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

VKAPI

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

Все запросы осуществляются к адресу https://api.vk.com/method/

После слэша идёт наименование используемого API-метода и передаются GET-параметры запроса. Ответ так же приходит по HTTPS в формате JSON.

TELEGRAM BOT API

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

Запросы осуществляются по адресу

https://api.telegram.org/bot(token)/METHOD_NAME

Где token выражает секретный ключ.

Запросы посылаются через HTTPS соединения, название метода указывается через слэш к основному адресу. Ответ приходит в формате JSON.

OPEN WEATHER MAP API

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

Формат работа: HTTP передача по api.openweathermap.org/data/2.5/weather?id= c указанием идентификационного номера желаемого города. Ответ сервера: JSON.

GOOGLE MAPS API

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

Подобные возможности предлагает JavaScript API Google Maps. Модуль полностью скриптовой и работает на стороне браузера, поэтому HTTP-запросы из PHP и формирование заголовков на стороне сервера, как было в других API, нам не нужно.

Например, выставление метки на карте будет выглядеть так:

var mark = new google.maps.Marker({
position: myPOS,
map: map,
title:»Hello!»
});

Популярные API

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

• Facebook API позволяет логиниться на сторонних платформах с помощью своего аккаунта, оплачивать покупки в приложении, получать доступ к данным крупных и средних аккаунтов Instagram Business, управлять страницами сообществ и публиковать на них контент, получать статистику по рекламе, управлять объявлениями и аудиторией, запускать прямые эфиры,
• С помощью Twitter API можно показывать ленту твитов на сайте, управлять профилем и настройками учетной записи, автоматически создавать рекламные кампании в Твиттере и управлять ими,
• API ВКонтакте дает возможность отслеживать активность пользователей в сообществах, создавать ботов, собирать статистику по действиям в сообществе, автоматически модерировать контент, автоматизировать работу с товарами (например, импорт из внешней базы), получать текстовые публикации из ВКонтакте по заданным ключевым словам и т.д.,
• Telegram Bot API представляет собой HTTP-интерфейс для работы с ботами в Telegram,
• YouTube API позволяет встраивать видео на сайт, создавать плейлисты, встраивать плеер в приложение, получать данные об активности пользователей.

Не менее популярны и следующие API:

Яндекс API – у всех популярных сервисов Яндекса есть свои API (Вебмастер, Метрика, Директ, Маркет, Аудитории, Карты и т.д.), благодаря которым можно:

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

Google API

• Работа с устройствами и приложениями на платформе Android,
• Управление событиями в Календаре,
• Управление товарами и акккаунтом в Google Покупках,
• Управление файлами на Google Диске, включая загрузку, скачивание, поиск, изменение прав доступа,
• Просмотр и управление данными Google Analytics,
• Чтение и редактирование файлов в Документах,

Как API помогают писать надёжные программы

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

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

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

Сделано это для того, чтобы сторонние программы могли:

• Взаимодействовать с файловой системой;
• Создавать графику;
• Сохранять и хранить важные данные;
• Пользоваться сетевыми возможностями;
• Запускать видео, аудио и другое.

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

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

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

API для дизельных двигателей двигателей

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

Наименование стандарта	Статус	Год выпуска	Ссылка
CA Полную информацию о стандарте CA API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1950	Подробнее
CB Полную информацию о стандарте CB API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1959	Подробнее
CC Полную информацию о стандарте CC API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1961	Подробнее
CD Полную информацию о стандарте CD API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1990	Подробнее
CD-II Полную информацию о стандарте CD-II API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1990	Подробнее
CE Полную информацию о стандарте CE API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1990	Подробнее
CF Полную информацию о стандарте CF API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1990	Подробнее
CF-2 Полную информацию о стандарте CF-2 API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1994	Подробнее
CF-4 Полную информацию о стандарте CF-4 API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1994	Подробнее
CG-4 Полную информацию о стандарте CG-4 API вы можете получить, нажав на ссылку подробнее.	Устаревший стандарт	1994	Подробнее
CH-4 Полную информацию о стандарте CH-4 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	1998	Подробнее
CI-4 Полную информацию о стандарте CI-4 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	2002	Подробнее
CI-4 PLUS Полную информацию о стандарте CI-4 PLUS API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	2002	Подробнее
CJ-4 Полную информацию о стандарте CJ-4 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	2010	Подробнее
CK-4 Полную информацию о стандарте CK-4 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	2017	Подробнее
FA-4 Полную информацию о стандарте FA-4 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	2017	Подробнее

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

Введение в 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

Плюсов у использования API немало:

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

Но также есть и минусы:

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

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

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

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

Пример API и тестовая матрица

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

Предположим, что подмножеством нашего API является конечная точка /users, которая включает следующие вызовы API:

Вызов API	Действие
GET /users	Просмотреть всех пользователей
GET /users?name={username}	Получить пользователя по имени пользователя
GET /users/{id}	Получить пользователя по ID
GET /users/{id}/configurations	Получите все конфигурации для пользователя
POST /users/{id}/configurations	Создать новую конфигурацию для пользователя
DELETE /users/{id}/configurations/{id}	Удалить конфигурацию для пользователя
PATCH /users/{id}/configuration/{id}	Обновить конфигурацию для пользователя

Где {id} — это UUID, а все конечные точки GET позволяют фильтровать, сортировать, исключать и ограничивать дополнительные параметры запроса для фильтрации, сортировки и разбивки на страницы тела ответа.

Основные позитивные тесты (позитивный путь по умолчанию)Позитивные тесты + необязательные параметры проверокНегативное тестирование – валидный ввод данныхНегативное тестирование — неверные входные данныеДеструктивное тестирование

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

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

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

Уровни зрелости API

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

Безопасность и авторизация

• Убедитесь, что API разработан в соответствии с правильными принципами безопасности: отказ по умолчанию, безопасное падение сервиса, принцип наименьших привилегий, отклонение всех невалидных данных в запросе и т. д.

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

  • Негативные тесты: убедитесь, что API отклоняет все несанкционированные вызовы.

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

Проверка протокола: проверьте HTTP / HTTPS в соответствии со спецификацией

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

Политики ограничения скорости, троттлинга и политики контроля доступа

Нагрузочные тесты (позитивные), стресс-тесты (негативные)

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

Соблюдайте правильный порядок ошибок

Во-первых, всегда показывайте неразрешимые ошибки прежде разрешимых:

— какой был смысл получать новый , если заказ все равно не может быть создан?

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

Плохо:

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

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

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